ProxyGen and Open Client Usage¶

ProxyGen and Open Client Usage

Introduction¶

Converted 4GL code can be called over the network in FWD. This is a functional replacement for the use of the Java Open Client to access the 4GL classic appserver /APSV transport in PASOE. Any code using the Progress Software Corp. Java Open Client, must be rewritten to use the equivalent Java classes in FWD. These classes are NOT "drop-in replacements" for the Java Open Client. This means that a developer must do some mapping/rework of the code but it is important to note that the core functionality is the same so it is not a huge project to rework the Java code.

ProxyGen¶

Open Client support for invoking programs on the appserver are supported in FWD both in an automated way (by interpreting the .xpxg files) and via an explicit way, using the FWD's equivalent APIs for OpenClient directly (in other words, you directly use the low-level APIs to connect to the appserver and perform invocations). This section describes the supported features from the .xpxg files, which are used by FWD to generate high-level Java classes, which in turn allow a more high-level mechanism of performing invocations on the appserver.

In OpenEdge, ProxyGen is used to generate source files for both .NET and Java. FWD uses as input the .xpxg files with the configuration of the exposed programs, and generates Java classes in a way similar to the OpenEdge's Java OpenClient; although there is not a one-to-one mapping of the result, the offered functionality is the same. More, FWD does not generate different code if the .xpxg file is configured for .NET export, it is the same as if it was configured for Java. Instead, if the .xpxg was meant to generate .NET code, there are runtime configurations which will need to be used when the legacy .NET OpenClient code will be refactored to Java, to make it .NET-compatible.

From the .xpxg structure, FWD supports most of the features. This includes the AppObject and SubAppObject configurations (specifying how the exposed programs are grouped in generated Java source code). Also, FWD allows specifing programs to be ran in any mode (non-persistent, persistent, single-run or singleton).

All 4GL parameter data types allowed for OpenEdge OpenClient are supported, this includes dataset, table, dataset-handle and table-handle (FWD will generate their definitions). Note that blob, clob, comhandle, object or jobject (a FWD extension) are not supported either in FWD or OpenEdge. Also, the parameters are not resolved from the .xpxg file, but from the actual 4GL program file - this results in some limitations, see the last paragraph of this section.

The type mapping of the parameter data type to Java data type is:

character and longchar are mapped to java.lang.String
decimal is mapped to java.math.BigDecimal
integer is mapped to java.lang.Integer if the parameter is extent or the AppObject/AllowUnknown flag is true; otherwise, Java int native type is used.
int64 is mapped to java.lang.Long if the parameter is extent or the AppObject/AllowUnknown flag is true; otherwise, Java long native type is used.
rowid is mapped to java.lang.Long
logical is mapped to java.lang.Boolean if the parameter is extent or the AppObject/AllowUnknown flag is true; otherwise, Java boolean native type is used.
memptr is mapped to the special com.goldencode.p2j.util.MemoryBuffer FWD type
raw is mapped to byte[]
date, datetime and datetime-tz are mapped to java.util.GregorianCalendar
handle is mapped to java.lang.Long

All parameter modes (INPUT, OUTPUT, INPUT-OUTPUT) are supported.

Limitations¶

The limitations at the time of this writing are:

Only Java code is generated. The FWD version of ProxyGen does not generate .NET code.
Each proxied program must appear in only one .xpxg file.
useRetVal (Return ABL RETURN-VALUE in the ProxyGen tool) - this is always available via the response in FWD
The Parameter#allowUknown attribute in the .xpxg is not supported - only the default AppObject/AllowUnknown is honored.
The configuration of these attributes at the (Sub)AppObject node is not determined at this time:
- AppObject/IsTTResultSet
- AppObject/WriteDatasetBeforeImage and ProcDetail/usesBeforeImageDefault
- ProcDetail/usesTTMappingDefault
- ProcDetail/usesUnknownDefault

Configuration¶

The Java source code for the equivalent OpenClient classes is generated during conversion. For this, the .xpxg files need to be specified, in the p2j.cfg.xml file. Add a parameter named proxy-programs-cfg, like:

<parameter name="proxy-programs-cfg" value="abl/proxy/" />

for which the value will represent:

a single .xpxg file OR
the location of a directory, which will be recursively searched for all .xpxg files

Note that the locations specified are relative to the P2J_HOME directory.

More configuration details can be found at ProxyGen configuration.

Java Open Client Usage¶

An application using the legacy OpenClient APIs requires refactoring to work with FWD; depending if there is generated code using the proxies, and on the complexity of the application, this may take from a few days to weeks. Expect changes to be made in every file which uses the legacy OpenClient proxies or APIs.

The analysis for the refactoring should start with how the OpenClient connection to the 4GL server is managed: determine how this connection is configured, created and managed. Ideally, there would be only a few places creating a connection, and these parts would be needed to migrate to FWD. From FWD side, understand what configuration needs to be provided (see Establishing a Connection section in Replacing the Open Client for Java).

Next is finding where and how the OpenClient Java proxy instances are used; analyze the lifetime of these objects, when/where they get created and destroyed. Note that the connection to the FWD server (and the OpenClient proxy instances in FWD) are not thread-safe, and they should not be cached or otherwise shared among threads.

The documentation at Replacing the Open Client for Java needs to be analyzed, as it will help you understand how your application will migrate, considering:

management of objects ran persistent
how to run an external program or an internal procedure/function
how parameters are passed, and read back (for OUTPUT/INPUT-OUTPUT) read from the response.
how exceptions are treated

If your application uses table or dataset parameters, these will require manual changes in each and every place where ProDataGraphMetaData , ProDataGraph, ProDataObject, etc types are used: FWD doesn't define these types, the types exposed via OpenClient to work with a dataset/table are all the basic types from Tuscany SDO (which OpenEdge extends via their Pro... types); for this part, analysis is required to determine:

if there are dynamically created tables or datasets (a.k.a ProDataGraph instances), where the runtime decides:
- which indexes are defined
- the fields added to the table
- the dataset's table and relation
if you read a DataGraph in a dynamic way, which requires going over all metadata, like tables, fields, indexes, etc.
how the static table/dataset parameters will be rewritten, from the OpenEdge approach to the FWD approach
how the dataset/table response is read back from the call
how the row's fields are read - there should be minimal change in this part, as FWD uses the DataObject APIs to access a row

Depending on the design of the application, the approach to follow can be:

analyze the Java code associated with the FWD OpenClient proxy files, generated by FWD conversion
migrate the code, to establish a connection to the FWD server
get a few small files, which uses a small set of OpenClient features, and migrate them first
expand with more complex files

The Calling 4GL Code via the Appserver API chapter in the Developer Guide's has more complete details on the specific Java Open Client replacement/mappings.

.NET Open Client Usage¶

At this time, there is no tested support for replacing the .NET Open Client. It is possible to provide this using the existing Java Open Client replacement. Please see #3326 for details.

Project

General

Profile

FWD

Wiki