Presenting Safe X3 Java Bridge Server - Sage City Community · The component "Safe X3 Java Bridge Server" is thus a multi-session process. NB: In a Java Bridge server, only the Adxwhat

Presenting Safe X3 Java Bridge Server

Research & Developpement – Safe X3 Java Bridge Server page 2

Content Content ............................................................................................................................................. 2 Prerequisites...................................................................................................................................... 3 Reminder: calling inter-solution processings ....................................................................................... 3

Goal ............................................................................................................................................... 3 Structure ........................................................................................................................................ 3 Calls "Calliu" and "Funciu" ............................................................................................................... 3

Principles .................................................................................................................................... 4 Example: .................................................................................................................................... 4

The Java Bridge server. ..................................................................................................................... 5 Concept overview ........................................................................................................................... 5 Delivered Bundles .......................................................................................................................... 6

The library bundles ..................................................................................................................... 6 Core bundles............................................................................................................................... 7 Functional bundles ...................................................................................................................... 8 The bundle used to qualify the extension capacities ..................................................................... 8

Installation and configuration of the component .............................................................................. 9 Available functionalities .................................................................................................................... 11

Brief overview .............................................................................................................................. 11 Carrying out HTTP requests .......................................................................................................... 11 SOAP Web Service calls ................................................................................................................ 12

Manipulation of Beans ............................................................................................................... 13 Creating and sending multi-part messages .................................................................................... 15 Results of type grid: Array[ ] ......................................................................................................... 16 Broker management ..................................................................................................................... 17

Extensibility of the Java Bridge server .............................................................................................. 18 Automatic find .............................................................................................................................. 18 Development of new plug-ins ....................................................................................................... 18

Connection pools ............................................................................................................................. 19 Creation and update ..................................................................................................................... 19 Information .................................................................................................................................. 19

Qualification tools ............................................................................................................................ 20 OSGI controls ............................................................................................................................... 20 The Java client ............................................................................................................................. 22 L4G processings ........................................................................................................................... 22


Prerequisites

runtime 15r.126 or higher

Reminder: calling inter-solution processings

Goal

In order to add easily technical functionalities to the X3 platform, a new component was added: the Java

Bridge server.

Structure

In order to avoid developments in the traditional X3 engine, it was decided to make available a request for

a processing to be carried out in another Adonix server.

ADONIX

Package B

ERP

Application

Server

ADONIX

Package A

PAY

Application

Server

Calls "Calliu" and "Funciu"

In the Adonix server of a traditional X3 engine, it is now possible to open a session with another Adonix

server belonging or not to the same solution and request that a processing be carried out synchronously

via a "Calliu" or "Funciu" instruction.

Adonix Server A

Process A

Adonix Server B

Process B

Subprog B1(P1,P2)Calliu "B:B1" with P1,P2 using [CNX]

Connection « CNX »


Principles

Opening of a connection

o OpAdxd "host:port" With 7,folder,language,x3user,x3pass Using [abbreviation]

o Several connections can be opened

Calls in a connection:

o Calliu "processing:spgm" With setups,… Using [abbreviation]

o Funciu "processing:func" Using [abbreviation] With (setups,…)

Closure

o OpAdxd Using [abbreviation]

Example:

Local Integer WNBITEM

Onerrgo CLOSEADX

# opening a link to a remote Adonix server

Opadxd "aydaix03.acy.adx:4150" With 7,"myFolder","FRA","myUserId","myPassword" Using [DIAMOND]

# calling a function in the remote Adonix server identified by the abbreviation "DIAMOND"

WNBITEM = Funciu "STOCKSERVICES:GETAVAILABLES" Using [DIAMOND] With ( WITEMREF,WSTOSITE )

# calling a sub-program in the remote Adonix server identified by the abbreviation "DIAMOND"

Calliu "STOCKSERVICES:MAJSTOCK" With WSTOSITE,WITEMREF,WNBITEM Using [DIAMOND]

$CLOSEADX

# calling a link established with the remote Adonix server identified by the abbreviation "DIAMOND"

Opadxd Using [DIAMOND]


The Java Bridge server.

The component « Sage X3 Java server » has the same presence as a traditional X3 engine: it listens to a

port just as the "deamon adxd" does.

Clients connecting to this port will find the same dialog as with the "deamon adxd" of a traditional X3

engine; they thus can request the launch of a "specific server".

Adonix SessionDeamon

Caller (other runtime, Java client, …)

Listener

Java X3 Runtime (JVM)

1

2

3

When a client "starts the Adonix server" of the Java Bridge server, a context is created in the JVM instance.

This session lasts until the socket is closed (see explicit closure or "killed" client)

The component "Safe X3 Java Bridge Server" is thus a multi-session process.

NB: In a Java Bridge server, only the Adxwhat and Adonix sessions having "t" and "7" as an identifier can

be instantiated; the other capacities of traditional runtimes (see Sadfsq, Sadora or Sadsql) are not

implemented.

Concept overview

The component "Safe X3 Java Bridge Server" is an extensible server which publishes technical

functionalities for the application server of the "Sage MGE X3" softwares.


JAVA

BRIDGE

SERVER

ADONIX

Package B

ERP

Application

Server

ADONIX

Package A

PAY

Application

Server

RPC

RPC

Delivered Bundles

The component "Safe X3 Java Bridge Server" is now developed in Java around an OSGI framework.

The published functionalities are implemented in the form of "OSGI bundles".

OSGI

ECLIPSE / EQUINOX

AX

IS2

EM

AIL

HT

TP

CLI

XALA

N

WRAPPER

SHARED.JA

VA

SHARED.X3CLIENT

SHARED.BUNDLES

MA

IN

BR

OA

DC

AS

TE

R

QU

ALIF

IER

DEAM

ON

HTTPCLIENT

MAILCLIENT

SOAPCLIENT

Library Bundles

Technical Bundles

Functional Bundles

Extensions Bundles

SAMPLE

Tools Apache httpclient .

Methods : get, post, put, delete

Web Services REST calls

Manipulates:

The html content and text content

Attachments (blob and url)

Embedded Images (blob and url)

Tools Apache Axis 2.

Wsdl => Stubs generation.

Doc => Javadoc generation.

Web Services SOAP calls

The library bundles

As their names go, these bundles are "osgifications" of Apache libraries and of the multi-platform service

wrapper "tanuki.wrapper"

• com.sage.x3.bundle.lib.apache.axis2


• com.sage.x3.bundle.lib.apache.email

• com.sage.x3.bundle.lib.apache.httpcli

• com.sage.x3.bundle.lib.apache.xalan

• com.sage.x3.bundle.lib.tanuki.wrapper

Sage libraries: these bundles are "osgifications" of Sage libraries which are used as a basis to develop other

Java components of Sage MGE

• com.sage.x3.bundle.shared.java

• com.sage.x3.bundle.shared.x3clients

This bundle contains a sub-group of technical classes, abstract classes and interfaces used in all bundles

belonging to Sage MGE.

• com.sage.x3.bundle.shared.bundles

Core bundles

com.sage.x3.bridge.bundle.main

It implements:

• various services including Log (IServiceConsole), Trace (IServiceTrace), Configuration

(IServiceConfig), Extension bundle management (IServiceExtends), Resources (IServiceResources).

• http server

• the configuration visualization controls

com.sage.x3.bridge.bundle.broadcaster

It implements the message broadcasting service () used by bundles to transmit event messages.

com.sage.x3.bridge.bundle.qualifier

It implements the qualification controls and the script interpreter

com.sage.x3.bridge.bundle.daemon


It implements:

• the deamon listening to the calls sent by the Adonix server.

• the object instance broker

• the interpreter of RPS calls sent by the Adonix servers.

Functional bundles

com.sage.x3.bridge.bundle.httpclient

It publishes the implementation of generic http clients used to launch http requests aiming at calling the

RESTFull Webservices

It depends on the bundle com.sage.x3.bundle.lib.apache.httpcli wrapping the library Apache

HttpComponents HttpClient v4

com.sage.x3.bridge.bundle.mailclient

It publishes the implementation of a generic mail sender.

It depends on the bundle com.sage.x3.bundle.lib.apache.email wrapping the library Apache commons

email v1.1

com.sage.x3.bridge.bundle.soapclient

It publishes:

• a stub generator

• A Javadoc document generator

The bundle used to qualify the extension capacities

This is a bundle which was developed "outside" the Bridge server context. It is loaded via the man bundle's

extension service.

This bundle corresponds to what a BP developer can integrate in the Bridge server

com.sage.x3.bridge.bundle.sample

It publishes:

• Beans manipulation functions


• Java Array manipulation functions

• date display functions

Installation and configuration of the component

For the installation and configuration of the component Safe X3 Java Bridge Server, the same procedure

applies as for other components.


It is possible to verify whether the Web interface delivered by Jetty is available.

URL: http://serveur_bridge:httpport


Available functionalities

Brief overview

The X3 Bridge Java server manipulates object instances

It sends to the Adonix server:

• either values of type native:

Booleans are not currently available.

• or references to object instances:

X3=1 , X3=2 , X3=3 , … , X3=n

Carrying out HTTP requests

An L4G processing can create an http client via a connection to a Java server.

Local Char KTARGETNEWHTTP (250)

KTARGETNEWHTTP = "com.sage.x3.runtime.bundle.httpclient.CServiceHttpClientImpl:newHttpClient"

Local Char WHTTPCLI (30)

WHTTPCLI = Funciu = KTARGETNEWHTTP Using [JAVSRV] With ( )

The instance of "CHttpClient" obtained can be called using several methods:

See X3HttpClientObject in SDK javadoc.

JAVA Byte Short Integer BigDecimal Date String String Byte [ ]

L4G Libelle Shortint Integer Decimal Date Char Clobfile Blobfile


Example using get() method:

Local Char WURL (250)

WURL = "http://www.webservicex.net/MortgageIndex.asmx?wsdl"

Local Char WHTTPREPLY (30)

WHTTPREPLY = Funciu = WHTTPCLI +":get" Using [JAVSRV] With ( WURL )

The instance of "CHttpResponse" obtained can be called using several methods:

Example using getText() method:

Local Clbfile WWSDL (8)

WWSDL = FUNCIU = WHTTPREPLY +":getText" Using [JAVSRV] With ( )

SOAP Web Service calls

Generation of a "stub" for a BP Web Service from its wsdl.

Local Char KTARGETGENST (250)

Local Char ASTUBID (30)

Local Char ATIMESTAMP (30)

KTARGETGENST = "com.sage.x3.runtime.bundle.webservices.CServiceStubsImpl:generate"

ASTUBID = "MortgageIndex"

ATIMESTAMP = "20091210093225"

Local Char WSTUBGENREP (30)

WSTUBGENREP = Funciu = KTARGETGENST Using [JAVSRV] With (ASTUBID,ATIMESTAMP,WWSDL )

Generation of the corresponding JavaDoc and publication of the html pages via Jetty.

Local Char KTARGETGENSD (250)

KTARGETGENSD = "com.sage.x3.runtime.bundle.webservices.CServiceStubsImpl:generateDoc"

Local Char WDOCGENREP (30)

WDOCGENREP = Funciu = KTARGETGENSD Using [JAVSRV] With (ASTUBID)


It is not necessary to restart for the stub classes to be taken into account.

There are 2 types of methods:

• data of type simple

• data of type complex

Instantiation of the stub:

Local Char WSTUBINST(250)

WSTUBINST = Funciu "com.sage.x3.runtime.bundle.deamon.CToolFactoryStubs:newStub" Using [JAVASRV]

With("PriceGetter","http://stubServer.com/PriceGetter")

The stub methods manipulating simple-type data can be called directly from the L4G:

Local Char WBPC(30)

Local Char WITEM (30)

Local Integer WQTY

WBPC = "DIS001"

WITEM = "JL-KIT-PC-NGERE"

WQTY = 5

Local Decimal WPRICE

WPRICE = Funciu = WSTUBINST +":getPrice" Using [JAVASRV] With (WBPC,WITEM,WQTY)

Manipulation of Beans

Example for the creation of a bean by valuing n properties:

Local Char KTARGETNEWBEAN (250)

KTARGETNEWBEAN = "com.sage.x3.runtime.bundle.deamon.CToolFactoryBeans:newBean"

Local Char WFIELDSTOSET (250) # la liste des ids des propriétés du bean à valoriser

WFIELDSTOSET = "property1;property2;propertyZ"

WBEANINST = Funciu = KTARGETNEWBEAN Using [JAVASRV] With ("com.sage.mybean",WFIELDSTOSET, VARONE,

VARTWO,...)


Example for entering several bean properties:

Local Char KTARGETWRITBEAN (250)

KTARGETWRITBEAN = "com.sage.x3.runtime.bundle.deamon.CToolFactoryBeans:writeBean"

Local Char WFIELDSTOREAD(250) # la liste des ids des propriétés du bean à valoriser

WFIELDSTOREAD = "property1;property2;propertyZ"

WNBFIELDS = Funciu = KTARGETWRITBEAN Using [JAVASRV] With( WBEANINST, WFIELDSTOWRITE, VARONE,

VARTWO,...)

Example for reading several bean properties:

Local Char KTARGETREADBEAN (250)

KTARGETREADBEAN = "com.sage.x3.runtime.bundle.deamon.CToolFactoryBeans:readBean"

Local Char WFIELDSTOREAD(250) # la liste des ids des propriétés du bean à lire

WFIELDSTOREAD = "property1;property2;propertyZ"

WNBFIELDS = Funciu = KTARGETREADBEAN Using [JAVASRV] With( WBEANINST, WFIELDSTOREAD, VARONE,

VARTWO,...)

Example for calling a method manipulating complex-type data:

The method "GetMortgageIndexByWeek" of the stub "MortgageIndexStub" requires a bean of type

"MortgageIndexStub.GetMortgageIndexByWeek" upon input.

Instantiation of the stub:

Local Char WSTUB(250)

WSTUB = Funciu "com.sage.x3.runtime.bundle.deamon.CToolFactoryStubs:newStub" Using [JAVASRV]

With("MortgageIndex","http://www.webservicex.net/MortgageIndex.asmx")


Creation of the Setup bean:

Local Char WCLASSNAME(250)

WCLASSNAME = "net.stub.mortgageindex.MortgageIndexStub$GetMortgageIndexByWeek"

Local Char WLISTFIELDS(250)

WLISTFIELDS="Day,Month,Year"

Local Char WBEANA(30)

WBEANA = Funciu = KTARGETNEWBEAN Using [JAVSRV] With (WCLASSNAME,WLISTFIELDS,9,9,1994)

Calling the method GetMortgageIndexByWeek:

WBEANB = Funciu = WSTUB +":GetMortgageIndexByWeek" Using [JAVSRV] With (WBEANA)

Creating and sending multi-part messages

instantiation of the CMail object:

Local Char KTARGETNEWMAIL(250)

KTARGETNEWMAIL = "com.sage.x3.runtime.bundle.mail.CServiceMailImpl:newMail"

Local Char WMAIL (30)

WMAIL = Funciu = KTARGETNEWMAIL Using [JAVSRV] With ( )

Required procedure before sending the mail:

# Ajout de l'expediteur

Calliu = WMAIL+":setFrom" With "[email protected]", "Sage X3 Java Server" Using [JAVSRV]

# Ajout des destinataires

Local Char WTO(80)(1..10)

WTO(1)="[email protected]"

WTO(2)="[email protected]"

Calliu = WMAIL+":setTo" With (WTO) Using [JAVSRV]

# Ajout du sujet

Calliu = WMAIL+":setSubject" With ("Email 'riche' de test") Using [JAVSRV]


Other functionalities:

• Addition of resources by providing an URL.

• Addition of binary resources in the form of Blobs.

• Message body in the form of rich text.

• Message body in the form of raw text.

• Addition of attachments by providing an URL.

• Addition of attachments via Blobs.

• Addition of a text attachment

The send() method:

Local Date WDATE

WDATE = Funciu = WMAIL +":send" Using [JAVSRV] With ( )

Results of type grid: Array[ ]

Methods returning grids other than byte[] (Type L4G BLOB) result in an error.

In order to carry out such an operation, it is necessary to use the tools provided bt the class

CToolArrayReader of the plug-in com.sage.x3.runtime.bundle.deamon.

Example:

# Ouverture du canal Java

Opadxd "ecchambard-001:27160" With 7,nomap ,"FRA" ,adxusr ,password Using [JAVSRV]

# Instanciation du stub

Local Char WSTUB(30)

WSTUB = Funciu = KTARGETNEWSTUB Using [JAVSRV] With

("FootballPoolWebService","http://euro2008.dataaccess.eu/footballpoolwebservice.wso" )

# Creation du bean parametre AllGoalKeepers

Local Char WCLASSNAME(250)


WCLASSNAME = "net.stub.footballpoolwebservice.FootballPoolWebServiceStub$AllGoalKeepers"

Local Char WLISTFIELDS(250)

WLISTFIELDS="SCountryName"

Local Char WBEANPARAM(30)

WBEANPARAM = Funciu = KTARGETNEWBEAN Using [JAVSRV] With (WCLASSNAME,WLISTFIELDS,"France")

# Appel de la methode AllGoalKeepers

Local Char WRESP(30)

WRESP = Funciu = WSTUB +":AllGoalKeepers" Using [JAVSRV] With (WBEANPARAM)

# Appel de la methode getAllGoalKeepersResult

Local Char WARRAY(30)

WARRAY = Funciu = WRESP +":getAllGoalKeepersResult" Using [JAVSRV] With ()

# Preparation de l'appel de la methode getString

Local Char REFREADER

Local Char GOALS (255)(100)

WREFREADER = Funciu = KTARGETARRAYREADER Using [JAVSRV] With (WARRAY,"getString","String")

# Recuperation de la taille du tableau

Local Integer WSIZE

WSIZE = Funciu = WREFREADER + ":size" Using [JAVSRV] With ()

# Parcours du tableau

Local Integer WIDX

For WIDX = 0 To WSIZE-1

# Récupération de l'élément n°WIDX du tableau avec la methode getOneObject

GOALS(WIDX) = Funciu = WREFREADER + ":getOneObject" Using [JAVSRV] With (WIDX)

Next WIDX

Broker management

The Adonix server is not aware of the object instances in the X3 Bridge Java server.

Release of an instance:


Local Char KTARGETCLINST (250)

KTARGETCLINST = "com.sage.x3.runtime.bundle.deamon.broker.CBroker:clearInstance"

Calliu = KTARGETCLINST With (WONEINST) Using [JAVSRV]

Release of all the instances of the session:

Local Char KTARGETCLEAR(250)

KTARGETCLEAR = "com.sage.x3.runtime.bundle.deamon.broker.CBroker:clear"

Calliu = KTARGETCLEAR With Using [JAVSRV]

Extensibility of the Java Bridge server

Automatic find

• "Plug-ins" located in the directory "[install_tool]/originals/extends" are automatically found.

• The technical plug-in "com.sage.x3.runtime.bundle.main", which is the core element of the

component Sage X3 Java server, is loaded dynamically in the OSGI framework by the service

"com.sage.x3.shared.bundles.IServiceExtends" of the said plug-in.

• The demonstration plug-in "com.sage.x3.runtime.bundle.sample" delivered with the common

Bundles belongs to the extension Bundles.

Development of new plug-ins

• Tools capable of building a JAR archive containing a MANIFEST file.

• IDE Eclipse based on the Framework OSGI Equinox.

• Eclipse for RCP/Plug-in Developers (http://www.eclipse.org/downloads/)


Connection pools

Since version 108, the “Safe X3 Java Bridge Server” component has the ability to contact an X3 processing

server to call 4GL sub-programs directly. In this way, developers of “extends“ bundles will be able to

connect to the available connection pools using the SDK Client.

Creation and update

Pools are directly created from X3 in the GESAPB function.

When triggering the Validation button, a “.xml“ file is generated (adxpoolconfig_SOLUTION.xml) in the

“X3_ROOT/GEN/“ directory of the solution on the X3 application server. If a Bridge server is linked to the

solution (i.e. the solution.xml file contains its description), this Bridge server will be contacted via a

“funciu“ call for the pool update.

If several Bridge servers are linked to a solution, only the server whose description appears first will be

contacted upon screen validation. In that case, a manual update is possible via the “updatePools“ OSGI

command of the Bridge server involved or via the “Refresh” button of the Web interface:

osgi> updatePools

000000 Command [updatePools]

000000 Nbargs=[0]

251-09:56:19.666 CResourceManagerService | Update pools description for SOLSUPV6 solution.

09:56:19:666,I,Get File via HTTP

:http://server:80/Adonix_SOLSUPV6/X3_ROOT/GEN/adxpoolconfig_SOLSUPV6.xml

09:56:20:025,I,Get File OK.

251-09:56:30.510 CResourceManagerService | Update succeeded.

Information

The connection pools can be viewed from the Web interface of the Bridge server in the “POOLS X3“

section.


Some actions are available like stopping or locking a group of entries.

This information on the status of the pools is also provided by the OSGI command of the Bridge server:

- poolids (pids) Returns the list of available pools.

- poolEids (peids) Returns the list of available entries for the pool.

- poolEinfos (pei) Returns the information on a pool entry.

- poolEstate (pes) Returns the status of a pool entry.

Qualification tools

OSGI controls

---CCommandConsoleMain

- hhelp (hh) Lists the controls specific to the component "Safe X3 java bridge server".

- confsys (cs) Lists the "system properties" of the jvm for the component "Safe X3 java

bridge server".

- confsys (cs) Lists the "framework properties" of the osgi framework for the component

"Safe X3 java bridge server".

- confproxy (cp) Lists the configuration properties for the use of a proxy by the component

"Safe X3 java bridge server".

---CCommandConsoleQualifier

- qlflist (ql) Lists the available scripts in the folder "BridgeData/qualifier/scripts".

Returns a numbered list.

- qlfshow (qs) Displays the full source of the script with or without the inclusions.


- qlfrun (qr) Launches a qualification script.

Allows 1 optional setup.

[ script-uri or srcipt-number ]

- qlfrestore (qres)Restores the qualification scripts present in the folder

"BridgeData/qualifier/scripts" together with those delivered.

- qlfagain (qa) Relaunches the last qualification control "qlfxxx" executed.

---CCommandConsoleStubs

- stubwsdllist(swl)lists the wsdl files available in the folder "install_data/qualifier/wsdl".

- stubgen (sg) generation of a stub from a wsdl.

Allows 3 optional setups.

[ stubid [wsdl-uri [stamp]]]

the setup "stubid" can be the numerical index of the wsdl in the list

returned by the control "listwsdl".

- stubgendoc (sgd) generation of the Java documentation of a generated stub.


[ stubid ]

- stublist (sl) lists the generated stubs available in the folder

"install_data/extends/classes".

- tubnew (sn) instantiation of a stub.


[ stubid [ stubendpoint]]

- stubinfos (si) reading of a stub's information.


[ stubid ]

---CCommandConsoleSample

- sample Test control using the beans of the "extends" bundle named "sample".

Allows no setup.

---CCommandeConsoleHttp

- httpget instantiation of an http client and sending of a GET request.


[ url ]

[?] to display options.

- httppost instantiation of an http client and sending of a POST request.


[ url [ data]]

---XdtServerCommand

- xdtserver interrogates the xdtserver service


Enter 'xdtserver ?' to get more help

The OSGI console is used to launch controls managing the OSGI framework, but also to launch controls to

produce and qualify the component.

For instance: generating a stub, launching a qualification script, etc.

The Java client

Scripts of tests based on the scripting engine "Rhino" :

• beansuse.js

• common.js

• httpuse.js

• objectsuse.js

• QLFCIUERROR.js

• sendmail.js

• session_ouvre_ferme.js

• stubdocgen.js

• stubgen.js

• stubuse.js

L4G processings

Our qualification processings:

• QLFCIUUTILS

• QLFCIUERROR

• QLFCIUHTTP

• QLFCIUMAIL

• QLFCIUGENSTU

• QLFCIUWSMOMO

• QLFCIUWSMOWE


• QLFCIUWSFOOT

Documents

Presenting Safe X3 Java Bridge Server - Sage City Community · The component "Safe X3 Java Bridge Server" is thus a multi-session process. NB: In a Java Bridge server, only the Adxwhat