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