jBASE jRemote Client (Java)

User Guide
Page 1 Information in this document is subject to change without notice.
No part of this document may be reproduced or transmitted in any form or by any means,
electronic or mechanical, for any purpose, without the express written permission of TEEN!" #oldings N$.
%opyright &''&(&'') TEEN!" #oldings N$. *ll rights reser+ed.
Information in this document is subject to change without notice.
No part of this document may be reproduced or transmitted in any form or by any means,
electronic or mechanical, for any purpose, without the express written permission of TEEN!" #oldings N$.
%opyright &''&(&'') TEEN!" #oldings N$. *ll rights reser+ed.
Information in this document is subject to change without notice.
No part of this document may be reproduced or transmitted in any form or by any means,
electronic or mechanical, for any purpose, without the express written permission of TEEN!" #oldings N$.
%opyright &''&(&'') TEEN!" #oldings N$. *ll rights reser+ed.
Information in this document is subject to change without notice.
No part of this document may be reproduced or transmitted in any form or by any means,
electronic or mechanical, for any purpose, without the express written permission of TEEN!" #oldings N$.
%opyright &''&(&'') TEEN!" #oldings N$. *ll rights reser+ed.
Information in this document is subject to change without notice.
No part of this document may be reproduced or transmitted in any form or by any means,
electronic or mechanical, for any purpose, without the express written permission of TEEN!" #oldings N$.
%opyright &''&(&'') TEEN!" #oldings N$. *ll rights reser+ed.
Information in this document is subject to change without notice.
No part of this document may be reproduced or transmitted in any form or by any means,
electronic or mechanical, for any purpose, without the express written permission of TEEN!" #oldings N$.
%opyright &''&(&'') TEEN!" #oldings N$. *ll rights reser+ed.
Information in this document is subject to change without notice.
No part of this document may be reproduced or transmitted in any form or by any means,
electronic or mechanical, for any purpose, without the express written permission of TEEN!" #oldings N$.
%opyright &''&(&'') TEEN!" #oldings N$. *ll rights reser+ed.
Information in this document is subject to change without notice.
No part of this document may be reproduced or transmitted in any form or by any means,
electronic or mechanical, for any purpose, without the express written permission of TEEN!" #oldings N$.
%opyright &''&(&'') TEEN!" #oldings N$. *ll rights reser+ed.
Information in this document is subject to change without notice.
No part of this document may be reproduced or transmitted in any form or by any means,
electronic or mechanical, for any purpose, without the express written permission of TEEN!" #oldings N$.
%opyright &''&(&'') TEEN!" #oldings N$. *ll rights reser+ed.
,ocument re+isions
,ate *uthor %hanges ade
03/06/2008 Lucas Gut Initial revision
Page &
Contents
Introduction.................................................................................................................................................-
*ssumptions.................................................................................................................................................
,e+elopers /uide........................................................................................................................................)
j0emote pac1ages....................................................................................................................................)
j*gent......................................................................................................................................................)
%onnecting to j2*"E..............................................................................................................................)
*uthentication.....................................................................................................................................3
""4 Encryption....................................................................................................................................5
*dditional connection properties6.......................................................................................................5
%losing a connection...............................................................................................................................7
j0emote %lient *PI reference..................................................................................................................7
%alling j2% subroutines......................................................................................................................7
4ogging into a j2*"E account............................................................................................................7
!pening a j2*"E file........................................................................................................................1'
!perating on j2*"E files..................................................................................................................1'
Executing a j2*"E command...........................................................................................................11
!btaining the j2*"E internal date....................................................................................................1&
!btaining the j2*"E internal time....................................................................................................1&
%on+erting data in external format to internal j2*"E format..........................................................1&
%on+erting data in internal j2*"E format to external format..........................................................1&
!btaining the +alue of a named j2*"E %ommon +ariable...............................................................18
!btaining EI" specific meta data......................................................................................................18
Executing j94 :ueries.......................................................................................................................18
"tarting;Ending a transaction............................................................................................................1-
%apturing j2*"E standard output.....................................................................................................1-
0esources...................................................................................................................................................1.
Page 8
Introduction
This user guide provides detailed instructions on how to use the jBASE jRemote Client API.
jRemote (Client) is a jBASE component providing an API to perform jBASE operations remotel such as calling
su!routines or accessing jBASE files. The j"emote #lient API is availa!le to multiple development platforms $see
j"emote Pac%ages section for more details&.
jRemote Resource Adapter (jRemote RA) is a '#A compliant resource adapter allowing '(EE applications to
access a jBASE Enterprise Information Sstem $EIS& within a transactional conte)t. The '(EE #onnector
Architecture $'#A& specification* to which this resource adapter conforms* specifies the mechanisms and
contracts re+uired for this transactional interaction. '#A provides a 'ava technolog solution to the pro!lem of
connectivit !etween the man application containers and toda,s enterprise information sstems $EIS&.
Note- .ore information on the j"emote "A can !e found in the j"emote '#A "A user guide documentation.
jBASE Server
jAgent
'ava #lient App.
'ava j"emote #lient API
./ET #0 #lient App.
#0 j"emote #lient API
This diagram shows how 'ava and ./ET #0 client applications ma use jRemote (Client) to access jBASE
functionalit. jAgent is a jBASE component responsi!le for accepting and processing incoming client re+uests.
jAgent* as well as j"emote* use T#P soc%et connections to communicate !etween each other and therefore need
to !e configured to use the same T#P port.
Page -
Assumptions
This document descri!es man concepts and methodologies that are highl technical in nature* and as such
prere+uisite %nowledge of the following is considered essential-
'ava Standard Edition
.icrosoft ./ET 1ramewor%
.icrosoft ./ET #0 programming concepts
jBASE and concepts of .ultivalue data!ases
Secure Soc%ets 2aer $SS2& protocol
Page .
Developers uide
The following section provides a detailed guide on how to connect and access the jBASE server.
jRemote pac!ages
j"emote API is currentl availa!le to the following development platforms-
Java
"icroso#t $NE% C&
This document covers the j"emote API for 'ava platform. Please refer the jBASE j"emote #lient $#0&
documentation for more information a!out this API on #0 platform.
The Java version of j"emote is distri!uted as a 'ava Archive $jar& file $jremote$jar&. This archive must !e located
in our #2ASSPAT3 in order to !e used ! a java application. The j"emote class li!rar is defined under the
com.jbase.jremote namespace. Please read the appropriate class li!rar $javadoc& documentation for more
information a!out this API.
jAgent
jBASE jAgent is a server4side jBASE component which must !e listening on a user4defined T#P port on the
remote jBASE instance. It accepts soc%et connections to process incoming re+uests from #lient Applications
implementing the j"emote #lient API. Please refer to the jBASE jAgent user guide for more information on how to
configure and start jAgent.
Connecting to jBASE
j"emote connection handles are o!tained via the JConnectionFactory interface which is implemented !
j"emote5s DefaultJConnectionFactory class. This interface provides several
getConnection()
methods to esta!lish a new connection with a remote jBASE instance. 1or more information please refer to the
API documentation.
Some of these methods accept java.util.Properties 6 Sstem./ame7alue#ollection o!jects as a parameter and
are used to suppl connection properties $The availa!le connection properties are highlighted in 'lue&.
A second option to suppl connection properties is to use the getter and setter methods implemented in
DefaultJConnectionFactory. The samples included in this section use the getter and setter methods.
Page ) Information in this document is subject to change without notice.
No part of this document may be reproduced or transmitted in any form or by any means,
electronic or mechanical, for any purpose, without the express written permission of TEEN!" #oldings N$.
%opyright &''&(&'') TEEN!" #oldings N$. *ll rights reser+ed.
The following connection properties are used to specif the target host-
(ost 89efault value- local(ost:
Specifies the host address
port 89efault value- )***):
Specifies the port num!er
try {
DefaultJConnectionFactory cxf = new DefaultJConnectionFactory();
cxf.setHost("127.0.0.1");
cxf.setort(20002); !!ort s"oul# $atc" t"e %ort &'(ent is listenin( on
JConnection cx = cxf.(etConnection();
return cx;
) catch (J*e$ote+xce%tion e) {
!! error
)
Aut(entication
jAgent can !e configured to verif user credentials and perform jBASE account authentication. j"emote
implements the following connection properties to suppl user credentials-
user
Specifies the user to !e authenticated
pass+ord
Specifies the user5s password
;ne of the following methods should then !e used depending on whether the current authentication mode is user
or account-
getConnection$String user* String password&
create a new connection and provide user and password as user credentials for
authentication
getConnection$String user* String account* String password&
Same as a!ove !ut suppling jBASE account details.
try {
DefaultJConnectionFactory cxf = new DefaultJConnectionFactory();
cxf.setHost("127.0.0.1");
cxf.setort(20002); !!ort s"oul# $atc" t"e %ort &'(ent is listenin( on
JConnection cx = cxf.(etConnection("$y,ser-a$e". "$yass/or#");
Page 3
!!JConnection cx = cxf.(etConnection("os,ser". "$y'ccount". "$y'ccntass/or#");
return cx;
) catch (J*e$ote+xce%tion e) {
!! error
)
SS, Encr-ption
jAgent ma !e configured to use SS2 encrpted connections for deploment scenarios which re+uire enhanced
securit. j"emote implements the following connection properties-
SS, 89efault value- #alse:
Specifies whether the connection should use SS2 encrption. SS2 should onl !e used
if the jAgent instance running on the jBASE server has also !een configured to accept
SS2 connections.
'ava j"emote #lients currentl must set the following propert-
Naive%rust"anager 89efault value- #alse:
This will force the 'ava j"emote #lient to trust all server certificates.
Certi#icateDN
try {
DefaultJConnectionFactory cxf = new DefaultJConnectionFactory();
cxf.setHost("127.0.0.1");
cxf.setort(20002);
cxf.ena0le112(); !!+na0le 112 encry%tion
cxf.ena0le-ai3e4rust5ana(er(); !!4rust all ser3er cre#entials
JConnection cx = cxf.(etConnection("$y,ser-a$e". "$yass/or#");
return cx;
) catch (J*e$ote+xce%tion e) {
!! error
)
Additional connection properties.
compression 89efault value- #alse:
This propert specifies whether the data transferred !etween client and server should !e
compressed. Ena!ling compression ields a !etter throughput on large data transfers. The
opposite effect ma occur on small data transfers and therefore j"emote will automaticall
decide whether to appl compression or not !ased on the supplied threshold value.
compression/t(res(old 89efault value- *:
Page 5
This propert is onl applica!le if compression is on and defines the threshold used to
decide whether a certain re+uest is going to !e compressed. 9ata transfers whose si<e is
less than the specified threshold are not compressed. 7alue = means all data will !e
compressed.
Closing a connection
After finishing with the connection* it must !e closed to release the associated resources-
cx.close();
jRemote Client API re#erence
This API provides client applications with a set of interfaces to access the remote jBASE server. A reference to a
JConnection instance should have !een o!tained* as detailed in the previous sections. 1or more information on
how to use this API* please read the j"emote API javadoc documentation.
Calling jBC su'routines
call(String subroutineName, JSubroutinearameters parameters)
2ocation- JConnection
"eturn tpe- JSubroutinearameters
Throws- JSubroutineNotFound!"ception, J#emote!"ception>
JSubroutinearameters represents the input6output parameters for the jB# su!routine and is an arra of
JDyn$rray values.
!!1%ecify su0routine %ara$eters
J1u0routineara$eters %ara$s = new J1u0routineara$eters();
%ara$s.a##(new JDyn'rray("one"));
%ara$s.a##(new JDyn'rray("t/o"));
%ara$s.a##(new JDyn'rray("t"ree"));
!!Call &6C su0routine
J1u0routineara$eters returnara$s = cx.call("5y1u0routine". %ara$s);
!!1"o/ %ara$eters
1yste$.out.%rintln("1st %ara$eter7 " 8 returnara$s.(et(0).(et(1));
1yste$.out.%rintln("2n# %ara$eter7 " 8 returnara$s.(et(1).(et(1));
1yste$.out.%rintln("9r# %ara$eter7 " 8 returnara$s.(et(2).(et(1));
,ogging into a jBASE account
switc%$ccount(String user, String account, String password)
Page 7
2ocation- JConnection
"eturn tpe- boolean
Throws- J#emote!"ception>
!!1/itc" &6'1+ account
boolean s/itc":; = cx.s/itc"'ccount("5y,ser-a$e". "5y'ccount". "5yass/or#");
0pening a jBASE #ile
open(String fileName)
2ocation- JConnection
"eturn tpe- JFile
Throws- J#emote!"ception>
!!:%en &6'1+ file
JFile $yFile = cx. o%en("5yFile-a$e");
0perating on jBASE #iles
A jBASE file must have !een opened prior to carring out an of these file operations. These are some of the
methods defined in interface JFile* to view all jBASE file operations please read the corresponding javadoc
documentation.

?rite a record to a previousl opened file
write(String record&ey, JDyn$rray record)
"eturn tpe- boolean
Throws- J#emote!"ception>
?rite a record to a previousl opened file preserving loc%s
write'(String record&ey, JDyn$rray record, boolean bloc(ed)rite)
"eturn tpe- boolean
Throws- J#ecord*oc(ed!"ception* J#emote!"ception>
"eads a record from an opened file
read(String record&ey)
"eturn tpe- JDyn$rray
Throws- J#ecordNotFound!"ception* J#emote!"ception
"eads a record from an opened file respecting loc%s or loc%s the specified record for update
readU$String record@e* !oolean !loc%ed"ead&
"eturn tpe- JDyn$rray
Throws- J#ecordNotFound!"ception* J#ecord*oc(ed!"ception*
J#emote!"ception
Read / Write example:
!!1%ecify recor# #ata
JDyn'rray recor# = new JDyn'rray();
recor#.re%lace("Fiel#1 test #ata". 1);
Page 1'
recor#.re%lace("Fiel#2 test #ata". 2);
!!<rite recor# to file
boolean /rite:; = file./rite("5y*ecor#=#". recor#));

!!*ea# recor# fro$ file
JDyn'rray recor#2 = file.rea#("5y*ecor#=#");
ReadU / WriteU example:
!!:0tain a recor# loc>
file.rea#,("5y*ecor#=#". true); !!4"is $et"o# call 0loc>s if anot"er t"rea# alrea#y
!!"as ac?uire# a loc> on t"is recor#
!!<rite recor# to file res%ectin( t"e recor# loc>
file./rite,("5y*ecor#=#". new JDyn'rray("Fiel#1 test #ata"). true);

!!*elease recor# loc>
File.release2oc>("5y*ecor#=#");
Non-blocking ReadU / WriteU example:
!!:0tain a recor# loc>
try {
file.rea#,("5y*ecor#=#". false); !!4"is call /ill t"ro/ an exce%tion if anot"er
!!t"rea# "as ac?uire# a loc> on t"is recor#
catch(J*ecor#2oc>e#+xce%tion le) {
1yste$.out.%rintln("*ecor# is loc>e#.");
)
!!<rite recor# to file. 4"is /ill release t"e recor# loc>
file./rite("5y*ecor#=#". new JDyn'rray("Fiel#1 test #ata"). true);
E1ecuting a jBASE command
e"ecute(String fileName)
2ocation- JConnection
"eturn tpe- J!"ecute#esults
Throws- J#emote!"ception>
!!+xecute &6'1+ co$$an#
J+xecute*esults results = cx.execute("2=14 5@F=2+");
J1elect2ist return2ist = results.(et*eturn2ist();
=f(return2ist."as-ext()) {
1yste$.out.%rintln("1st ite$ of 1elect list7 " 8 return2ist.next());
)
1yste$.out.%rintln("C'4,*=-A7 " 8 results.(etCa%turin(Bar().to1trin(());
1yste$.out.%rintln("1+44=-A7 " 8 results.(et1ettin(Bar().to1trin(());
Page 11
0'taining t(e jBASE internal date
date()
2ocation- JConnection
"eturn tpe- int
Throws- J#emote!"ception>
!!:0tain t"e &6'1+ internal #ate
int $yDate = cx. date();
0'taining t(e jBASE internal time
time()
2ocation- JConnection
"eturn tpe- int
Throws- J#emote!"ception>
!!:0tain t"e &6'1+ internal ti$e
int $yDate = cx. time();
Converting data in e1ternal #ormat to internal jBASE #ormat
icon+(String data, String con+ersion)
2ocation- JConnection
"eturn tpe- String
Throws- J#emote!"ception>
!!Con3ert #ate to internal &6'1+ for$at
1trin( result = cx.icon3("02!02!200C". "D2!");
assert+?uals("19CDE". result);
Converting data in internal jBASE #ormat to e1ternal #ormat
ocon+(String data, String con+ersion)
2ocation- JConnection
"eturn tpe- String
Throws- J#emote!"ception>
!!Con3ert #ate to internal &6'1+ for$at
1trin( result = cx.ocon3("t"is is a test". "5C,");
assert+?uals("4H=1 =1 ' 4+14". result);
Page 1&
0'taining t(e value o# a named jBASE Common varia'le
getCommon(String name)
2ocation- JConnection
"eturn tpe- JDyn$rray
Throws- J#emote!"ception>
!!:0tain 3alue of a &6'1+ Co$$on 3aria0le
JDyn'rray 3alue = cx.(etCo$$on("5yCo$$on");
1yste$.out.%rintln("Balue of na$e# co$$on 5yCo$$on7 " 8 3alue.(et(1));
0'taining EIS speci#ic meta data
get,etaData()
2ocation- JConnection
"eturn tpe- !-S,etaData#epository
Throws- J#emote!"ception>
!!:0tain a $eta #ata 3alue
+=15etaData*e%ository $#*e% = cx.(et5etaData();
JDyn'rray &# = $#*e%.(et*e%ository+ntry("5@F*+:1=4:*@F+-4*@");
1yste$.out.%rintln("Balue of $eta #ata entry7 " 8 &#.(et(1));
E1ecuting j2, 3ueries
createStatement()
2ocation- JConnection
"eturn tpe- JStatement
Throws- J#emote!"ception>
e"ecute()
2ocation- JStatement
"eturn tpe- J#esultSet
Throws- J#emote!"ception>
!!+xecute &G2 ?uery
J1tate$ent state$ent = cx.create1tate$ent();
J*esult1et rs = state$ent.execute("2=14 5@F=2+ H'1");
/"ile(rs.next()) {
JDyn'rray &# = rs.(et*o/();
1yste$.out.%rintln(&#.(et(1));
)
Page 18
Starting4Ending a transaction
begin()
commit()
rollbac(()
2ocation- JConnection
"eturn tpes- +oid
Throws- J#emote!"ception>
!!1tart a transaction an# %erfor$ a roll0ac>
cx.0e(in();
$yfile./rite("5y*ecor#=#". ne/ JDyn'rray("5y test #ata"));
cx.roll0ac>();
!!1tart a transaction an# %erfor$ a co$$it
cx.0e(in();
$yfile./rite("5y*ecor#=#". ne/ JDyn'rray("5y test #ata"));
cx.co$$it();
Capturing jBASE standard output
set.erminal/utput)riter()riter writer)
2ocation- JConnection
"eturn tpe- +oid
Throws- /othing
!!1et t"e /riter for t"e ter$inal out%ut to ca%ture stan#ar# out%ut
6yte'rray:ut%ut1trea$ 0os = ne/ 6yte'rray:ut%ut1trea$();
<riter /riter = null;
try {
/riter = ne/ :ut%ut1trea$<riter(0os. ",4FIE");
catc" (,nsu%%orte#+nco#in(+xce%tion e) {
1yste$.out.%rintln("+rror /"ile creatin( :ut%ut1trea$<riter.");
)
cx.set4er$inal:ut%ut<riter(/riter);
Page 1-
Resources
'ava '9@ http-66java.sun.com
.icrosoft ./ET 1ramewor% http-66msdn.microsoft.com6en4us6netframewor%6default.asp)
'(EE #onnector Architecture $'#A& Specification http-66java.sun.com6j(ee6connector6
'Boss http-66www.j!oss.org6
Page 1.