® 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 externalType externalType part and use dot syntax to reference the methods typeName typeName . . methodName(); methodName(); If the class or function is non-static (more typical) Create a variable based on its externalType externalType part – initialize it with a new new keyword Use it in much the same way you would a library name (use dot syntax for the methods) externalTypeVariable.methodName(); externalTypeVariable.methodName(); externalType Declaration externalType Declaration Two class variables Two class variables One custom method One custom method class “constructor method” class “constructor method” Variable of externalType(TaxModule) Variable of externalType(TaxModule) Create new (non-static) instance Create new (non-static) instance Initialize class variable values Initialize class variable values Call calculateTax routine Call 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 program program 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 new new 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 package package named: egljava egljava Right-click over Right-click over egljava egljava and create a new Java class named: HelloEGLworld HelloEGLworld Using the copy/paste code in the Notes, create your first Java class… Press Ctrl/S Press 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 program program Name the program: callJava callJava From within the code, copy/delete and replace the boilerplate code, with the complete program solution shown below, in the Notes Notes area of this slide Top section of callJava program Functions externalType Definition With your mouse cursor inside the source, press: • Ctrl/S Ctrl/S (why)? • Ctrl/G Ctrl/G (why)? 9 Workshop continued – Debug the EGL Program and Java Calls Add a Breakpoint to the callJava.egl callJava.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 [...]...Topic EGL and Remote Programs Sub-Topics: EGL Calls to Remote Programs (Overview) Java (terms and concepts) Calling Java using the externalType Part Calling Java using JavaLib Calling COBOL Programs Calling RPG Programs 11 EGL s JavaLib Built-in System Function If you are not calling a custom Java Class, but only calling a static Java API (think of these as Java library “built-in-functions”)... callcmdPgm .java 22 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,... over \Java Resources: src\egljava\ package and create a new Java Class named: InvokeEGL - Using the copy/paste code in the ***Notes 26 4 Call an EGL Program From Java – Run the Java Class From Project Explorer: Right-click over \Java Resources: src\egljava\ package\InvokeEGL .java …and select: Run As > 1 Java Application Note the Console when the run completes 27 5 Debug an EGL Program From Java. .. 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 23 ***Notes 1 Call an EGL Program From Java – Create the EGL Program From the \programs\ folder, under \EGLSource\ create a new EGL program named: JavaCallEGL Notes: Use this code – for the lab... 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 The debugger will stop at the breakpoint in the java code Step through the java code Note the variable values in the Java. .. 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 15 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 5 Debug an EGL Program From Java – Optional – 2 of 3 Create a new "EGL Listener" launch configuration From the Run Debug… Menu Select EGL Listener > New_configuration The Port: should be 8346 Click Apply – to save your configuration Click Debug – to launch the EGL listener ***Notes 29 5 Debug an EGL Program From Java – Optional – 3 of 3 Debug the Java Class calling the EGL program: ... break-points in the Java Class, and debug from Java to the EGL called program do this: Modify the Linkage Options for your called program (JavaCallEGL) library is the name of the EGL project containing the called program – in your case, specify: EGLWeb location is localhost – enter it, as shown below remoteComType is DEBUG – selected from the ComboBox Save your changes, and Generate JavaCallEGL 28 To... javaWrapper=“YES” specified Context Menu) 11 From EGL Default Build Descriptors, select for both: Target system build descriptor Debug build descriptor 12 Close the Properties view 13 Generate the JavaCallEGL program 25 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 \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/S – and you will get syntax errors in the code Add the following import statement to the top of the file: New Method 16 OPTIONAL Workshop – Passing a String Array – Modify the externalType From \Programs\callJava .egl – modify . From JavaResources :srcegljavaHelloEGLworld .java JavaResources :srcegljavaHelloEGLworld .java – add the following new method to the existing Java class. package named: egljava egljava Right-click over Right-click over egljava egljava and create a new Java class named: HelloEGLworld HelloEGLworld Using