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 TEMENOS Holdings NV.
Copyright 2002-2006 TEMENOS Holdings NV. All rights reserved.
Document revisions
Date Author Changes Made
03/06/2008 Lucas Gut Initial revision
Page 2
Contents
Introduction.................................................................................................................................................4
Assumptions................................................................................................................................................5
Developers Guide........................................................................................................................................6
jRemote packages....................................................................................................................................6
jAgent......................................................................................................................................................6
Connecting to jBASE..............................................................................................................................6
Authentication.....................................................................................................................................7
SSL Encryption....................................................................................................................................8
Additional connection properties:.......................................................................................................8
Closing a connection...............................................................................................................................9
jRemote Client API reference..................................................................................................................9
Calling jBC subroutines......................................................................................................................9
Logging into a jBASE account............................................................................................................9
Opening a jBASE file........................................................................................................................10
Operating on jBASE files..................................................................................................................10
Executing a jBASE command...........................................................................................................11
Obtaining the jBASE internal date....................................................................................................12
Obtaining the jBASE internal time....................................................................................................12
Converting data in external format to internal jBASE format..........................................................12
Converting data in internal jBASE format to external format..........................................................12
Obtaining the value of a named jBASE Common variable...............................................................13
Obtaining EIS specific meta data......................................................................................................13
Executing jQL queries.......................................................................................................................13
Starting/Ending a transaction............................................................................................................14
Capturing jBASE standard output.....................................................................................................14
Resources...................................................................................................................................................15
Page 3
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 remotely such as calling
subroutines or accessing jBASE files. The jRemote Client API is available to multiple development platforms (see
jRemote Packages section for more details).
jRemote Resource Adapter (jRemote RA) is a JCA compliant resource adapter allowing J2EE applications to
access a jBASE Enterprise Information System (EIS) within a transactional context. The J2EE Connector
Architecture (JCA) specification, to which this resource adapter conforms, specifies the mechanisms and
contracts required for this transactional interaction. JCA provides a Java technology solution to the problem of
connectivity between the many application containers and today's enterprise information systems (EIS).
Note: More information on the jRemote RA can be found in the jRemote JCA RA user guide documentation.
Java Client App. .NET C# Client App.
Java jRemote Client API C# jRemote Client API
jAgent
jBASE Server
This diagram shows how Java and .NET C# client applications may use jRemote (Client) to access jBASE
functionality. jAgent is a jBASE component responsible for accepting and processing incoming client requests.
jAgent, as well as jRemote, use TCP socket connections to communicate between each other and therefore need
to be configured to use the same TCP port.
Page 4
Assumptions
This document describes many concepts and methodologies that are highly technical in nature, and as such
prerequisite knowledge of the following is considered essential:
Java Standard Edition
Microsoft .NET Framework
Microsoft .NET C# programming concepts
jBASE and concepts of Multivalue databases
Secure Sockets Layer (SSL) protocol
Page 5
Developers Guide
The following section provides a detailed guide on how to connect and access the jBASE server.
jRemote packages
jRemote API is currently available to the following development platforms:
Java
Microsoft .NET C#
This document covers the jRemote API for Java platform. Please refer the jBASE jRemote Client (C#)
documentation for more information about this API on C# platform.
The Java version of jRemote is distributed as a Java Archive (jar) file (jremote.jar). This archive must be located
in your CLASSPATH in order to be used by a java application. The jRemote class library is defined under the
com.jbase.jremote namespace. Please read the appropriate class library (javadoc) documentation for more
information about this API.
jAgent
jBASE jAgent is a server-side jBASE component which must be listening on a user-defined TCP port on the
remote jBASE instance. It accepts socket connections to process incoming requests from Client Applications
implementing the jRemote Client API. Please refer to the jBASE jAgent user guide for more information on how to
configure and start jAgent.
Connecting to jBASE
jRemote connection handles are obtained via the JConnectionFactory interface which is implemented by
jRemotes DefaultJConnectionFactory class. This interface provides several
getConnection()
methods to establish a new connection with a remote jBASE instance. For more information please refer to the
API documentation.
Some of these methods accept java.util.Properties / System.NameValueCollection objects as a parameter and
are used to supply connection properties (The available connection properties are highlighted in blue).
A second option to supply 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 6
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 TEMENOS Holdings NV.
Copyright 2002-2006 TEMENOS Holdings NV. All rights reserved.
The following connection properties are used to specify the target host:
host [Default value: localhost]
Specifies the host address
port [Default value: 20002]
Specifies the port number
try {
DefaultJConnectionFactory cxf = new DefaultJConnectionFactory();
cxf.setHost("127.0.0.1");
cxf.setPort(20002); //Port should match the port jAgent is listening on
JConnection cx = cxf.getConnection();
return cx;
} catch (JRemoteException e) {
// error
}
Authentication
jAgent can be configured to verify user credentials and perform jBASE account authentication. jRemote
implements the following connection properties to supply user credentials:
user
Specifies the user to be authenticated
password
Specifies the users password
One of the following methods should then be 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 above but supplying jBASE account details.
try {
DefaultJConnectionFactory cxf = new DefaultJConnectionFactory();
cxf.setHost("127.0.0.1");
cxf.setPort(20002); //Port should match the port jAgent is listening on
JConnection cx = cxf.getConnection("myUserName", "myPassword");
//JConnection cx = cxf.getConnection("osUser", "myAccount", "myAccntPassword");
return cx;
Page 7
} catch (JRemoteException e) {
// error
}
SSL Encryption
jAgent may be configured to use SSL encrypted connections for deployment scenarios which require enhanced
security. jRemote implements the following connection properties:
SSL [Default value: false]
Specifies whether the connection should use SSL encryption. SSL should only be used
if the jAgent instance running on the jBASE server has also been configured to accept
SSL connections.
Java jRemote Clients currently must set the following property:
NaiveTrustManager [Default value: false]
This will force the Java jRemote Client to trust all server certificates.
CertificateDN
try {
DefaultJConnectionFactory cxf = new DefaultJConnectionFactory();
cxf.setHost("127.0.0.1");
cxf.setPort(20002);
cxf.enableSSL(); //Enable SSL encryption
cxf.enableNaiveTrustManager(); //Trust all server credentials
JConnection cx = cxf.getConnection("myUserName", "myPassword");
return cx;
} catch (JRemoteException e) {
// error
}
Additional connection properties:
compression [Default value: false]
This property specifies whether the data transferred between client and server should be
compressed. Enabling compression yields a better throughput on large data transfers. The
opposite effect may occur on small data transfers and therefore jRemote will automatically
decide whether to apply compression or not based on the supplied threshold value.
compression_threshold [Default value: 0]
This property is only applicable if compression is on and defines the threshold used to
decide whether a certain request is going to be compressed. Data transfers whose size is
Page 8
less than the specified threshold are not compressed. Value 0 means all data will be
compressed.
Closing a connection
After finishing with the connection, it must be closed to release the associated resources:
cx.close();
jRemote Client API reference
This API provides client applications with a set of interfaces to access the remote jBASE server. A reference to a
JConnection instance should have been obtained, as detailed in the previous sections. For more information on
how to use this API, please read the jRemote API javadoc documentation.
Calling jBC subroutines
call(String subroutineName, JSubroutineParameters parameters)
Location: JConnection
Return type: JSubroutineParameters
Throws: JSubroutineNotFoundException, JRemoteException;
JSubroutineParameters represents the input/output parameters for the jBC subroutine and is an array of
JDynArray values.
//Specify subroutine parameters
JSubroutineParameters params = new JSubroutineParameters();
params.add(new JDynArray("one"));
params.add(new JDynArray("two"));
params.add(new JDynArray("three"));
//Call jBC subroutine
JSubroutineParameters returnParams = cx.call("MySubroutine", params);
//Show parameters
System.out.println("1st parameter: " + returnParams.get(0).get(1));
System.out.println("2nd parameter: " + returnParams.get(1).get(1));
System.out.println("3rd parameter: " + returnParams.get(2).get(1));
Logging into a jBASE account
switchAccount(String user, String account, String password)
Location: JConnection
Return type: boolean
Page 9
Throws: JRemoteException;
//Switch jBASE account
boolean switchOK = cx.switchAccount("MyUserName", "MyAccount", "MyPassword");
Opening a jBASE file
open(String fileName)
Location: JConnection
Return type: JFile
Throws: JRemoteException;
//Open jBASE file
JFile myFile = cx. open("MyFileName");
Operating on jBASE files
A jBASE file must have been opened prior to carrying out any 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.
Write a record to a previously opened file
write(String recordKey, JDynArray record)
Return type: boolean
Throws: JRemoteException;
Write a record to a previously opened file preserving locks
writeU(String recordKey, JDynArray record, boolean blockedWrite)
Return type: boolean
Throws: JRecordLockedException, JRemoteException;
Reads a record from an opened file
read(String recordKey)
Return type: JDynArray
Throws: JRecordNotFoundException, JRemoteException
Reads a record from an opened file respecting locks or locks the specified record for update
readU(String recordKey, boolean blockedRead)
Return type: JDynArray
Throws: JRecordNotFoundException, JRecordLockedException,
JRemoteException
Read / Write example:
//Specify record data
JDynArray record = new JDynArray();
record.replace("Field1 test data", 1);
record.replace("Field2 test data", 2);
Page 10
//Write record to file
boolean writeOK = file.write("MyRecordId", record));
//Read record from file
JDynArray record2 = file.read("MyRecordId");
ReadU / WriteU example:
//Obtain a record lock
file.readU("MyRecordId", true); //This method call blocks if another thread already
//has acquired a lock on this record
//Write record to file respecting the record lock
file.writeU("MyRecordId", new JDynArray("Field1 test data"), true);
//Release record lock
File.releaseLock("MyRecordId");
Non-blocking ReadU / WriteU example:
//Obtain a record lock
try {
file.readU("MyRecordId", false); //This call will throw an exception if another
//thread has acquired a lock on this record
catch(JRecordLockedException le) {
System.out.println("Record is locked.");
}
//Write record to file. This will release the record lock
file.write("MyRecordId", new JDynArray("Field1 test data"), true);
Executing a jBASE command
execute(String fileName)
Location: JConnection
Return type: JExecuteResults
Throws: JRemoteException;
//Execute jBASE command
JExecuteResults results = cx.execute("LIST MYFILE");
JSelectList returnList = results.getReturnList();
If(returnList.hasNext()) {
System.out.println("1st item of Select list: " + returnList.next());
}
System.out.println("CAPTURING: " + results.getCapturingVar().toString());
System.out.println("SETTING: " + results.getSettingVar().toString());
Page 11
Obtaining the jBASE internal date
date()
Location: JConnection
Return type: int
Throws: JRemoteException;
//Obtain the jBASE internal date
int myDate = cx. date();
Obtaining the jBASE internal time
time()
Location: JConnection
Return type: int
Throws: JRemoteException;
//Obtain the jBASE internal time
int myDate = cx. time();
Converting data in external format to internal jBASE format
iconv(String data, String conversion)
Location: JConnection
Return type: String
Throws: JRemoteException;
//Convert date to internal jBASE format
String result = cx.iconv("02/02/2005", "D2/");
assertEquals("13548", result);
Converting data in internal jBASE format to external format
oconv(String data, String conversion)
Location: JConnection
Return type: String
Throws: JRemoteException;
//Convert date to internal jBASE format
String result = cx.oconv("this is a test", "MCU");
assertEquals("THIS IS A TEST", result);
Page 12
Obtaining the value of a named jBASE Common variable
getCommon(String name)
Location: JConnection
Return type: JDynArray
Throws: JRemoteException;
//Obtain value of a jBASE Common variable
JDynArray value = cx.getCommon("MyCommon");
System.out.println("Value of named common MyCommon: " + value.get(1));
Obtaining EIS specific meta data
getMetaData()
Location: JConnection
Return type: EISMetaDataRepository
Throws: JRemoteException;
//Obtain a meta data value
EISMetaDataRepository mdRep = cx.getMetaData();
JDynArray jd = mdRep.getRepositoryEntry("MY_REPOSITORY_ENTRY");
System.out.println("Value of meta data entry: " + jd.get(1));
Executing jQL queries
createStatement()
Location: JConnection
Return type: JStatement
Throws: JRemoteException;
execute()
Location: JStatement
Return type: JResultSet
Throws: JRemoteException;
//Execute jQL query
JStatement statement = cx.createStatement();
JResultSet rs = statement.execute("LIST MYFILE *A1");
while(rs.next()) {
JDynArray jd = rs.getRow();
System.out.println(jd.get(1));
}
Starting/Ending a transaction
begin()
commit()
Page 13
rollback()
Location: JConnection
Return types: void
Throws: JRemoteException;
//Start a transaction and perform a rollback
cx.begin();
myfile.write("MyRecordId", new JDynArray("My test data"));
cx.rollback();
//Start a transaction and perform a commit
cx.begin();
myfile.write("MyRecordId", new JDynArray("My test data"));
cx.commit();
Capturing jBASE standard output
setTerminalOutputWriter(Writer writer)
Location: JConnection
Return type: void
Throws: Nothing
//Set the writer for the terminal output to capture standard output
ByteArrayOutputStream bos = new ByteArrayOutputStream();
Writer writer = null;
try {
writer = new OutputStreamWriter(bos, "UTF-8");
catch (UnsupportedEncodingException e) {
System.out.println("Error while creating OutputStreamWriter.");
}
cx.setTerminalOutputWriter(writer);
Page 14
Resources
Java JDK http://java.sun.com
Microsoft .NET Framework http://msdn.microsoft.com/en-us/netframework/default.aspx
J2EE Connector Architecture (JCA) Specification http://java.sun.com/j2ee/connector/
JBoss http://www.jboss.org/
Page 15
