Upload
donna-charles
View
215
Download
3
Tags:
Embed Size (px)
Citation preview
®
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