®

IBM Software Group

© 2006 IBM Corporation

EGL Calling Java

This Learning Module shows how to use EGL to call Java classes, methods and access class variables.

2

EGL externalType Part An externalType part provides the EGL mapping to a Java Class. This is similar to the mapping that an EGL Interface provides for Web Service functions, but extends to map Java class

variables and constructors.

Invoking ExternalType functions If the class or function is marked static,

Simply invoke it using the name of its externalTypeexternalType part and use dot syntax to reference the methods

typeNametypeName..methodName();methodName(); If the class or function is non-static (more typical)

Create a variable based on its externalTypeexternalType part – initialize it with a newnew keyword Use it in much the same way you would a library name (use dot syntax for the methods)

externalTypeVariable.methodName();externalTypeVariable.methodName();

externalType DeclarationexternalType Declaration

Two class variablesTwo class variables

One custom methodOne custom method

class “constructor method”class “constructor method”

Variable of externalType(TaxModule)Variable of externalType(TaxModule)

Create new (non-static) instanceCreate new (non-static) instance

Initialize class variable valuesInitialize class variable values

Call calculateTax routineCall calculateTax routine

3

EGL Calling Java Calling EGL – 1 of 2

The following types of transfer of control are possible in EGL: 1. EGL-generated Java™ program to EGL-generated Java program 2. Non-EGL (native or hand-coded) Java program to EGL program 3. EGL-generated Java program to non-EGL Java program 4. EGL-generated Java program to DLL 5. EGL-generated Java program to .EXE or .BAT file

1. EGL-generated Java programprogram to EGL-generated Java program Calling one EGL-generated program from another is as simple as invoking the Java class for the target

program using a call statement. Be aware, however, of package dependencies. You must invoke a class that is one of the following: Within the same package as the calling program. Qualified with a package name using dot syntax. Identified with a linkage option part.

2. Non-EGL Java program to EGL program To invoke an EGL-generated program from a non-EGL Java program, you must do one of the

following: Define the EGL program as a service – as we’ve seen in a prior unit. Create Java wrapper classes for the EGL program. See workshop, further back in this section.

3. EGL-generated Java program to non-EGL Java program To invoke non-EGL Java code from Java code generated by EGL, you must create an EGL

ExternalType – and a variable for the ExternalType. This EGL part contains function descriptions for the Java methods you wish to call. ExternalTypes are considered a Best Practice.

Invoke the Java method as follows: Create a variable based on the ExternalType part and use it in much the same way you would a library, appending

the ExternalType part variable name to the name of the method using dot syntax:– ExternalTypeVar.method();ExternalTypeVar.method();

4

EGL Calling Java Calling EGL – 2 of 2

EGL-generated Java program to .DLL You can call functions in a single, non-EGL dynamic link library (DLL) (written in, for

example, C or COBOL) from an EGL Java program. The file extension for the DLL depends on your environment (examples include .dll, .so, and .sl).

You create a Library part of type nativeLibrary to act as an interface between your EGL program and the DLL. The Library part lists function names and parameters, and can use the alias property of the functions where function names do not match EGL conventions.

Access the functions by using dot syntax (library.function()) or by creating a use declaration for the library to make its functions global to your program.

EGL-generated Java program to .EXE or .BAT file EGL provides two functions that allow you to call a system command (such as a .bat or

a .exe executable file). These were covered as optional exercises in a previous section: sysLib.callCmd();

– This function transfers control to a specified executable; when the executable terminates, control returns to the calling EGL program.

sysLib.startCmd(); – This function transfers control to a specified executable, then keeps running; both the EGL program and the

executable run at the same time.

Related concepts – See product help Transfer of control across programs Linkage options part

Related tasks – See product help Generating EGL and Web services Generating Java wrappers

5

EGL externalType for the HelloEGLworld Class The externalType we will use to interface with the HelloEGLworld Java class

EGL variable declaration for the externalType. Notes:EGL variable declaration for the externalType. Notes:

- Creates a - Creates a newnew instance of the Java class (in memory) instance of the Java class (in memory)

- Passes two values into the class variables- Passes two values into the class variables

6

Workshop – Create a Java Class and Call it From an EGL Program To see how all this works together, you will complete a workshop as follows (from 10,000 feet)

You will: Create a new Java Class Create a new EGL program that contains:

An EGL externalType of the Java Class Calls to the Java functions – through the externalType

Access of the Java class variables - through the externalType

After finishing that, we’ll do two additional things: Learn how to call Java API’s through the EGL JavaLib (built-in system) functions Pass string arrays back and forth between EGL and Java

Important Note:Important Note: Java is a case-sensitive language (okay we said that already). As such, be careful naming your classes and all the other files you create in this workshop, as the copy/paste code will pre-determine your part names.

7

Create a new Java Package and Class From Project Explorer: From Project Explorer:

Right-click over \Java Resources: src\ and create a packagepackage named: egljavaegljava

Right-click over Right-click over egljavaegljava and create a new Java class named: HelloEGLworldHelloEGLworld

Using the copy/paste code in the Notes, create your first Java class…

Press Ctrl/SPress Ctrl/S – to save and compile your .java source to a .class file

8

Workshop continued – Create a new EGL Program

From Project Explorer, right-click over the \EGLSource\programs\\EGLSource\programs\ directory, and create a new, EGL programprogram

Name the program: callJavacallJava From within the code, copy/delete and replace the boilerplate code, with the complete program

solution shown below, in the NotesNotes area of this slide

Top section of callJava program

Functions

externalType Definition

With your mouse cursor inside the source, press:

• Ctrl/SCtrl/S (why)?

• Ctrl/GCtrl/G (why)?

9

Workshop continued – Debug the EGL Program and Java Calls Add a Breakpoint to the callJava.eglcallJava.egl program From Project Explorer, right-click over the \EGLSource\programs\callJava.egl select Debug EGL Program…Debug EGL Program…

Step through the code

Note the variable values before and after the calls to the Java Class!

10

Additional Info on External Types

When creating external types, you may run into a Java ”final””final” type variable within the Java class you’re calling.

If you need to access this variable from EGL, it will need to be defined in your externalType. The syntax is the same as with any

other variable. Note, you do not need to include a “final” indicator.

Additionally, a cross-language conflict can occur when creating external types that have conflicting method/variable names. i.e. If the name of a Java method is the

same as an EGL reserved word, your externalType will not compile.

To fix this you must add the “JavaName” property to the function declaration.

Invalid

Valid

11

Topic

EGL Calls to Remote Programs (Overview)

Java (terms and concepts)

Calling Java using the externalType Part

Calling Java using Calling Java using JavaLibJavaLib

Calling COBOL Programs

Calling RPG Programs

Sub-Topics:

EGL and Remote ProgramsEGL and Remote Programs

12

EGL’s JavaLib Built-in System Function If you are not calling a custom Java Class, but only calling a static Java APIstatic Java API (think of these as

Java library “built-in-functions”) – you can dispense with having to define a new externalType, and call the API using the JavaLibJavaLib Built-in Function.

Here are the JavaLibfunction calls

We are interested in: invoke()invoke() store() store()

***Notes***Notes

13

EGL’s JavaLib invoke() and store() Functions With JavaLib you can:

invoke() – call a static Java API (i.e. call a class that does NOT need to be created as a new instance)

Format: JavaLib.invoke(“package.class”,”method”,<Optional parameter>);JavaLib.invoke(“package.class”,”method”,<Optional parameter>);

store() – call a non-Static Java API and return an Object (instead of a Java primitive)

Format: JavaLib.store(“objVariable” JavaLib.store(“objVariable” as "objID:java", “package.class", “method“);as "objID:java", “package.class", “method“);

Notes on store() You tell Java to create a new Class instance (i.e. an object) and store it, in a temporary variable identified as the first parameter to store()store() You add the boilerplate: as "objID:java", You specify which package.sub-package.class, etc. And the method that returns the Java object into the temporary variable

14

Workshop - EGL’s JavaLib invoke() and store() Functions From Project Explorer, edit the \EGLSource\programs\callJava.egl

Towards the end of the program (as shown here in the screen capture) insert the following two functions (found in the Notes section of this slide)

Un-comment the calls to these functions in the main()main() function

With your mouse cursor inside the source, press:

• Ctrl/SCtrl/S• Ctrl/GCtrl/G

15

Workshop continued – Debug the EGL Program and Java Calls From Project Explorer, right-click over the \EGLSource\programs\callJava.egl

select Debug EGL Program and once again, step through the code

16

OPTIONAL Workshop – Passing a String Array Between Java and EGL There are some situations in your projects where you may need to send an array of strings from EGL to Java. You would use an externalType to

do this (and – it’s pretty easy). Follow these steps to see how (easy )

From \JavaResources :src\egljava\HelloEGLworld.java\JavaResources :src\egljava\HelloEGLworld.java – add the following new method to the existing Java class (source code is in the Notes section of the slides):

Press Ctrl/SCtrl/S – and you will get syntax errors in the code. Add the following importimport statement to the top of the file:New

Method

17

OPTIONAL Workshop – Passing a String Array – Modify the externalType

From \Programs\callJava.egl \Programs\callJava.egl – modify the EGL externalType definition we’ve been using. Add a new function for the new Java Class method at the bottom of the externalType

Press:Press: Ctrl/SCtrl/S Ctrl/GCtrl/G

18

OPTIONAL Workshop – Passing a String Array – Create a new JSP Page

From \WebContent\\WebContent\ – As you’ve done before, create a new JSP page, named: callJavaPagecallJavaPage

For the page’s JSFHandler, add the following code (which you can copy from the Notes section below)

Notes:Notes: Import Import statement – provides reference-ability to the externalType definition – provides reference-ability to the externalType definition Two fixed-length string arraysTwo fixed-length string arrays – one initialized with values (to be passed into the Java Class), one empty that will contain data returned from the Java Class call – one initialized with values (to be passed into the Java Class), one empty that will contain data returned from the Java Class call Variable for the externalTypeVariable for the externalType to the Java Class – used in the previous workshop to the Java Class – used in the previous workshop

19

OPTIONAL Workshop – Passing a String Array – Create a new JSP Page

From Page Designer, and from Page Data, drag and drop: strArray2 – string[]strArray2 – string[] on to the page, and create output controls.

20

OPTIONAL Workshop – Run the Page on the Server Right-click over the page, and select Run on Server

Note the following: The Java class was called, and an array of strings was passed to the function The function concatenated the values passed in, with the literal “: Java” The array returned (and eventually displayed through the page’s dataTable) is a copy of this new data Open the Console view. Scroll up, and you’ll see the following SystemOut messages, written there by the

Java function

21

Optional Workshop – Debugging from EGL to Java - and back Open the HelloEGLworld.java program and set a breakpoint at the location you want the debugger to stop. Also set a breakpoint in callJava.egl following the java call. From Project Explorer, right-click over the \EGLSource\programs\callJava.egl select Debug EGL Program…Debug EGL Program…

The debugger will stop at the breakpoint in the java code.

Step through the javacode.

Note the variable values in the Java

Class.

If you continue to debug (step), the debuggerwill return to theEGL program andcontinue debugging.

22

Running a Java Batch Program

Besides debugging through your EGL/Java batch programs, you can run them by doing the following: From Java Resources: src Expand the programs

folder Right-click over the .java

file you wish to run Select:

Run As > 2 Java Application

Note that, unless your program does anything external (writes to files, etc.) you won’t see anything.

Run: callcmdPgm.javacallcmdPgm.java

23

OPTIONAL TOPIC – Calling EGL From Java Classes Using JavaWrappers

As mentioned in the beginning of this unit, you can call EGL programs, from native (hand-coded) Java classes.

To do this, you will “wrap” the EGL programs and their parameters with EGL “Java Wrappers”. What are Java Wrappers? Java classes that simplify calling EGL programs from Java Your Java code works with Java types, and conversion to EGL types is performed

automatically by the wrapper.

Steps:1. Create the EGL Program

Code Syntax check and validate

2. Create a new build descriptor with options set for wrapping an EGL program– Set the build descriptor option: enableJavaWrapperGen = YES enableJavaWrapperGen = YES

Create a CallLink (Linkage Option) element for the EGL called program, with:– type = remoteCall, javaWrapper = YES

Assign to the JavaWrapper Build Descriptor to the new program Generate the Program

3. Create (code) the native Java Class and Save (which will generate)

4. Run the Java Class – which will call your EGL program

5. Optionally – Debug starting from the Java Class, calling EGL ***Notes***Notes

24

1. Call an EGL Program From Java – Create the EGL Program

From the \programs\\programs\ folder, under \EGLSource\ create a new EGL program named:

JavaCallEGLJavaCallEGL

Notes: Use this code – for the lab (see screen capture) Make the program name start with an upper-case character

The generated JavaWrapper will have an upper-case character, by default

The Notes contains this code (if you’re in a hurry )

Save (Ctrl/S)Save (Ctrl/S) and make sure you have no syntax errors

25

2. Call an EGL Program From Java – Create a New Build Descriptor

As you did earlier in the course, create a new EGL Build create a new EGL Build Descriptor for your new programDescriptor for your new program, following these detailed directions:

From the Project Explorer, copy the existing batchBuildFile options:1. Right-click over batchBuildFile.eglbld and select: Open With > Text Editor2. From inside the file: Press Ctrl/A (to select all) … then Ctrl/C (to copy all

selected text to the Windows buffer)3. Close the file

Next create a new EGL build file, and paste the copied entries into it:4. From Project Explorer, right-click over \EGLSource\ and select: New > New >

Other…Other… Expand EGL and select: EGL Build FileEGL Build File

5 From the next wizard, name the file: JavaWrapBuildDescriptorJavaWrapBuildDescriptor6. Close the new build file (you need to re-open and edit it in Text Editor mode)7. Reopen JavaWrapBuildDescriptor file using the Text Editor

8. From the ***Notes***Notes part of this slide, copy and paste the contents

9. Save your changes (Ctrl/S)(Ctrl/S) and close the file

Assign (associate) the new JavaWrapBuildDescriptor to the new program and Generate the program:

10. From Project Explorer, right-click over your new JavaCallEGLProgram - Under \EGLSource\programs\\EGLSource\programs\ select:

PropertiesProperties (note this option is usually at or near the bottom of the Context Menu)

11. From EGL Default Build Descriptors, select <JavaWrapBuildDescriptor.eglbld> for both:

Target system build descriptorTarget system build descriptor Debug build descriptorDebug build descriptor

12. Close the Properties view

13. GenerateGenerate the JavaCallEGL program the JavaCallEGL program

From the above, note the following:From the above, note the following: Standard <BuildDescriptor…> entriesStandard <BuildDescriptor…> entries <ResourceAssocations…> entry, <ResourceAssocations…> entry,

Which would be used if the programWhich would be used if the program

accessed an external fileaccessed an external file LinkageOptions entry (named javaWrapOption)LinkageOptions entry (named javaWrapOption)

With a single <callLink> entry With a single <callLink> entry For a <remoteCall…> to your EGL programFor a <remoteCall…> to your EGL programWith option: javaWrapper=“YES” specifiedWith option: javaWrapper=“YES” specified

26

3. Call an EGL Program From Java – Create the Java Class

As you did earlier in the course, create a new Java Class file, following these detailed instructions:

From Project Explorer: From Project Explorer: Right-click over \Java Resources: src\egljava\ package and create a new

Java Class named: InvokeEGLInvokeEGL - Using the copy/paste code in the ***Notes***Notes

27

4. Call an EGL Program From Java – Run the Java Class

From Project Explorer: From Project Explorer: Right-click over

\Java Resources: src\egljava\ package\InvokeEGL.java

…and select:

Run As > Run As >

1. Java Application1. Java Application

Note the Console when the Note the Console when the run completesrun completes

28

5. Debug an EGL Program From Java – Optional – 1 of 3

You may want to set break-points in the Java Class, and debug from Java to the EGL called program. To do this:

Modify Modify the Linkage OptionsLinkage Options for your called program (JavaCallEGL)

library library is the name of the EGL project containing the called program – in your case, specify: EGLWebEGLWeb location location is localhostlocalhost – enter it, as shown below remoteComType remoteComType is DEBUGDEBUG – selected from the ComboBox

SaveSave your changes, and Generate JavaCallEGLGenerate JavaCallEGL

29

5. Debug an EGL Program From Java – Optional – 2 of 3Create a new "EGL Listener" launch configuration Create a new "EGL Listener" launch configuration

From the From the Run Debug…Run Debug… Menu Menu Select EGL Listener > New_configurationSelect EGL Listener > New_configuration

The Port: should be The Port: should be 83468346 Click Click ApplyApply – to save your configuration – to save your configuration Click Click DebugDebug – to launch the EGL listener – to launch the EGL listener

***Notes***Notes

30

5. Debug an EGL Program From Java – Optional – 3 of 3

Debug the Java Class calling the EGL program: Add breakpoints to the both the Java Class file and

EGL program source From Project Explorer, Right-click over the Java

Class, and select: Debug As > 3 Java Application Resume or step through the Java code Step or Resume through the EGL code

31

OPTIONAL Workshop – Access the HTTP Servlet Header

In many web applications you will need to access what is called the HTTP Servlet Header – which contains information such as the: Login name User Role Test – defined for a given page Path

To do that, you can nest Java externalType definitions as shown in this example:

32

OPTIONAL Workshop – Access the HTTP Servlet Header – 1 of 3

Add new EGL externalTypeexternalType definitions

Under \EGLSource\ open:

comcom

ibmibm

eglegl

jsfjsf

FacesContextFacesContext

Select and replace all of its contents, with the externalTypesexternalTypes in the Notes section of this slide.

33

OPTIONAL Workshop – Access the HTTP Servlet Header – 2 of 3

New .jsp.jsp page

Create a new web page, named: readServletHeader.jspreadServletHeader.jsp (use a template)

In Page Designer, change the default heading text, and Edit the EGL for the page.

Replace the default JSFHandler with the statements from the Notes section of this slide

Read the comments to see how to access a “3-deep nested Java Object” (the Request object) – Press Ctrl/S

JSF Handler Part

34

OPTIONAL Workshop – Access the HTTP Servlet Header – 3 of 3

From Page Data, drag hRechRec onto the page.

Create read/only output fields

Run the page on the server You should see something like what is

shown in the screen capture below If you were logged in to an external server,

you would see additional variable information.

35

OPTIONAL Workshop – Access the URL of the Current Page

In many web applications you will need to access just the URL – of the current page. That is, the left-most portion of the URL (minus the page name and .JSP extension). This consists of: http:// Domain name Application/Context root (in our case: EGLWeb) and sub-directories

To do this, you will once again rely on Java externalTypes and some EGL procedural code, written by Scott Pecnik/IBM

36

OPTIONAL Workshop – Access the URL of the Current Page – 1 of 3

Add new EGL externalTypeexternalType definitions

Under \EGLSource\ open:

comcom

ibmibm

eglegl

jsfjsf

FacesContextFacesContext

Select and replace all of its contents, with the externalTypesexternalTypes in the Notes section of this slide.

You may have already made changes for the previous (servletHeader) workshop. Still, there are

37

OPTIONAL Workshop – Access the URL of the Current Page – 2 of 3

New .jsp.jsp page

Create a new web page, named: getURL.jspgetURL.jsp (use a template)

In Page Designer, change the default heading text, and Edit the EGL for the page.

Replace the default JSFHandler with the statements from the Notes section of this slide

JSF Handler Part

38

OPTIONAL Workshop – Access the URL of the Current Page – 3 of 3

From Page Data, drag requestURLrequestURL onto the page.

Create a read/only output field

Run the page on the server You should see something like what is shown in

the screen capture below If you’re using WebSphere the port # (8080) will

be either 9080, or 9081

39

OPTIONAL Lab – Sending eMail Using EGL and RBD

One of the standard requirements for Web Applications is to programmatically send eMail, from server-side logic. This is very easy to do using EGL, a Java Class that does the mail send, and a page.

Steps: Create a new Java class that accesses the JavaMailJavaMail API Create an externalTypeexternalType for the class Use the externalTypeexternalType in your EGL business logic – calling it from an EGL Logic

Part

We’ll do an example of this using a Web Page, but note that you could also call JavaMail using batch EGL (programs) just as easily. ***Notes

To: xxxxFr: xxxxSubject: xxxxxContent: xxxxx

Send

JSFHandler…externalTypeCall Java Class

Java Class…Invoke JavaMail…

WAS

40

Step 1 – Create Java Class to Invoke SendMail API JavaMail is an API that is used to send eMail from Java Classes. You’ve already created a new

Java Class so this should be fairly straightforward.

From Navigator, Right-click over Right-click over

egljavaegljava and create a new Java class named: SendMailSendMail

Using the copy/paste code in the Notes, create the SendMail Java class…

You will need to modify the line for mail.host – and enter the name of your SMTP mail server

41

Step 2 – Create a New Web Page From \WebContent\\WebContent\ - Right-click, and create a new, Web Page

named: eMailPage.jspeMailPage.jsp Change the default page header text and edit the EGL Page Code

Replace the existing boiler-plate code with the statements in the NotesNotes section of this slide. Review this code, and press Ctrl/SCtrl/S – to save and generate your JSFHandler

42

Step 3 – Create the Web Page Controls

From Page Designer/Page Data Drag: em – eMailRec onto the page Create an input form (input fields)

and a submit button

Drag sendMailFunc() on top of the submit button

43

Step 4 – Run the Page – Check out the eMail!

Run the page on the server, enter a valid email address and press the Send Mail (submit button)

Wait a few seconds (perhaps a bit longer) and check your eMail

44

Mapping Between EGL and Java Types

EGL typeEGL type Java typeJava type

CHAR, CHAR?, MBCHAR, MBCHAR?, DBCHAR, DBCHAR?, UNICODE, UNICODE?

java.lang.String, with trailing blank removal/padding and truncation on transitions

UNICODE(1), UNICODE(1)? char, java.lang.Character

STRING java.lang.String

HEX(2), HEX(2)? byte, java.lang.Byte

HEX(>2), HEX(>2)? byte[]

BOOLEAN, BOOLEAN? boolean, java.lang.Boolean

SMALLINT, SMALLINT? short, java.lang.Short

INT, INT? int, java.lang.Integer

BIGINT long, java.lang.Long

DECIMAL, BIN, MONEY, NUM (no decimal places) 1<=length<=9, int 10<=length<=18, long 19<=length<=31, java.math.BigInteger

DECIMAL?, BIN?, MONEY?, NUM? (no decimal places) 1<=length<=9, java.lang.Integer 10<=length<=18, java.lang.Long 19<=length<=31, java.math.BigInteger

DECIMAL, DECIMAL?, BIN, BIN?, MONEY, MONEY?, NUM, NUM? (declared with decimal places)

java.math.BigDecimal

SMALLFLOAT, SMALLFLOAT? float, java.lang.Float

FLOAT, FLOAT? double, java.lang.Double

DATE, DATE? java.sql.Date

TIME, TIME? java.sql.Time

TIMESTAMP, TIMESTAMP? java.sql.Timestamp

INTERVAL, INTERVAL? (microseconds) java.math.BigInteger (microseconds)

INTERVAL, INTERVAL? (months) long (months)

BLOB, CLOB n/a

Dynamic array java.util.List. The elements of the dynamic array are converted to Java types according to this table.

45

Now that you have completed this topic, you should be able to:

Create a new EGL externalType for a Java class Create an EGL variable for the externalType Call the Java Class through the externalType, and access:

Static Class Variables Non-static Class Variables Static Methods Non-static Methods

Pass data into the externalType via parameters Pass and return string arrays Call JavaLib built-in functions to access static Java APIs

Topic Summary

Summary