JavaBBjBridge

Calling a BBj Program From a Java Program

The package com.basis.bbj.bridge provides classes that may be used to call a BBj program from within a Java program. The calling Java program uses a BBjBridgeRequest to specify the program to be called as well as command line parameters to be passed to that program. Additionally, the calling Java program may write data into the BBjBridgeRequest. That data then becomes available to the called BBj program through a channel that is OPENed within the called BBj program. The BBj program can write data to that same channel and the calling Java program can obtain whatever data was written by the called BBj program by querying a BBjBridgeResponse.

For more detailed information about these classes, click here.

Opening the Bridge Plugin Device

The BBjBridge plugin needs to be defined in the config.BBx file as a Java plugin device (an aliased device that starts with "J"), which specifies the plugin com.basis.bbj.bridge.BBjBridgeOpenPlugin (BBj-specific OPEN verb).

For example:

ALIAS J0 com.basis.bbj.bridge.BBjBridgeOpenPlugin

 

The BBj program opens the bridge device using the following code:

BRIDGE = UNT

OPEN (BRIDGE)"J0"

It is important to note that the bridge device may only be opened once. Any subsequent attempt to open the device within the same session will fail.

Reading Data From the Plugin Device

The FIN information for a BBjBridgeOpenPlugin device has the template:

"RequestRecordOriented:u(1),ResponseRecordOriented:u(1)"

The called BBj program can determine whether the OPENed channel contains record-oriented data or string-oriented data as follows:

DIM BRIDGE$:TMPL(BRIDGE,IND=0)

BRIDGE$ = FIN(BRIDGE,IND=0)

isRecordOriented = BRIDGE.RequestRecordOriented

Writing Data to the Plugin Device

The called BBj program may write data to the bridge device using the WRITE verb. The calling program may write to the bridge channel as though it were a string file or it may write to the device as though it were a record-oriented file. Once the BBj program has used a string-oriented WRITE, all record-oriented WRITEs will fail. Similarly, once the program has used a record-oriented WRITE, all string-oriented WRITEs will fail. The BBj program may choose either write method regardless of whether the input side of the device is string-oriented or record-oriented.

Program Termination

The BBj program that is being called from the bridge must terminate by calling RELEASE. If the called BBj program does not do a RELEASE, then the calling Java program will either time out or block until the called BBj program does a RELEASE.

Persistence Of Channels, Variables, Environment and ADDRd Programs

As seen from the Java program, a JavaBBjBridge can be used to make multiple calls to execute (the same or different) BBj programs. By setting parameters when creating the JavaBBjBridge the calling Java program declares whether channels that were OPENed within the called BBj program (and were not CLOSEd by that program) should persist through consecutive calls to runBBj(). If the bridge was created with p_channelsPersist set to true, then the call to RELEASE will not close any open channels. Similarly, changes to STBL and SETOPTS will persist through subsequent calls if p_environmentPersists was set to true; all variables will persist if p_variablesPersist was true; and if p_addrsPersist was true then any ADDR d programs will remain in memory between calls to runBBj().

For sample code, see Sample BBj Program and Sample Java Program.

Use of a JavaBBjBridge in a Debugger

When running a Java program that contains a BBjBridge in a Debugger, the use of a breakpoint or step function may cause the suspension of all threads of the Java program, including the JavaBBjBridge. By default, the server to which the BBjBridge is connected will disconnect and terminate if the server finds the BBjBridge uncommunicative.

The JavaBridgeRequest provides a method, setPersistOnTimeout(boolean), which informs the BBjBridge and it's corresponding server that it should persist despite appearing uncommunicative. This method should be called prior to any breakpoint and before passing the BBjBridgeRequest to runBBj.

The following is an example code fragment:

BBjBridgeRequest request = JavaBBjBridgeFactory.createBridgeRequest(); /* set the BBjBridge to persist even after becoming uncommunicative */ request.setPersistOnTimeout(true); BBjBridgeResponse response = JavaBBjBridgeFactory.createBridgeResponse(); bridge.runBBj(request,response,TIMEOUT);

Using the JavaBBjBridge in Multiple Threads

The JavaBBjBridge is not threadsafe, meaning multiple threads should not attempt to share the same instance of the JavaBBjBridge. Instead, the JavaBBjBridge should be instantiated in one thread and its use restricted to that same thread.

Package com.basis.bbj.bridge

Interface Summary
BBjBridgeRequest	BBjBridgeRequest is used to specify a program that is to be called by JavaBBjBridge, to pass parameters to that program and to provide data that can be read by that program from an ALIAS bbj channel.
BBjBridgeResponse	After calling BBjBridge.runBBj() the BBjBridgeResponse will contain any data that has been written to the ALIASed bbj channel by the called bbj program.
JavaBBjBridge	A JavaBBjBridge allows a Java program to execute a BBj program and to communicate to that program using BBjRequest and BBjResponse.

Class Summary
BBjBridgeOpenPlugin	This BBj plugin is used in conjunction with JavaBBjBridge and provides the connection between BBjBridgeRequest / BBjBridgeResponse and a channel that can be opened by the BBj program.
JavaBBjBridgeFactory	JavaBBjBridgeFactory provides a factory interface for obtaining instances of JavaBBjBridge, BBjBridgeRequest and BBjBridgeResponse.
TestBridge	TestBridge is a demo program that demonstrates the usage of JavaBBjBridge.

Exception Summary
BBjBridgeException	An Exception type used in bridge package.