PWB519 Accessing Third-Party Enterprise JavaBeans Servers from PowerBuilder 9.0

1. PWB519 Accessing Third-Party Enterprise JavaBeans Servers from PowerBuilder 9.0 Jim O’NeilPrincipal Technical Support EngineerSybase, Inc. (Concord, MA)joneil@sybase.com

2. Accessing Third-Party EJB Servers Agenda • Overview of the Enterprise JavaBeans (EJB) Model • PowerBuilder EJB client implementation • Coding a PowerBuilder EJB client application • Deploying PowerBuilder NVOs to EJB servers • Additional resources

3. Accessing Third-Party EJB Servers Agenda • Overview of the Enterprise JavaBeans (EJB) Model • PowerBuilder EJB client implementation • Coding a PowerBuilder EJB client application • Deploying PowerBuilder NVOs to EJB servers • Additional resources

4. Overview of the Enterprise JavaBeans Model Core Concepts EJB is Sun’s J2EE transactional, vendor-neutral, enterprise component architecture providing • Modeling of business entities and synchronous and asynchronous processes • Persistence via explicit code (bean-managed) or via services of the EJB server (container-managed) • Vendor neutrality and interoperability • XML driven deployment and configuration

5. Overview of the Enterprise JavaBeans Model Core Concepts EJB types • Session beans model processes • Stateless EJBs are reusable and ‘single-task’ oriented • Stateful EJBs remain associated with a client and are disposed when client is through • Entity beans model objects that persist, often in the form of records in a database • Message-driven beans respond to asynchronous requests from the Java Message Service (JMS)

6. Overview of the Enterprise JavaBeans Model Representative Enterprise JavaBeans Server and Client Application Client Application J2EE Server JNDI Service InitialContext lookup EJB Home homeinterface stub createfindByPrimaryKey EJB Object EnterpriseInformation System remoteinterface stub business method Implementation class Message-driven bean return value  ancillary Java classes onMessage topic/queue messages External messaging client applications Java Message Service

7. Overview of the Enterprise JavaBeans Model Interfaces and Classes Java Naming and Directory Interface (JNDI) • Provides a standardized way of accessing resources in a distributed environment • Protocol and naming service agnostic • DNS • NDIS • LDAP • X.500 • Implemented by the javax.naming package and three other packages below it • javax.naming.InitialContext is the entry point to the EJB Server • bind – associates a name with an object • lookup – finds an object given the name

8. Overview of the Enterprise JavaBeans Model Interfaces and Classes Home interface • Provides remote client-view of methods affecting the EJB lifecycle • Extends javax.ejb.EJBHome • Can include business methods that are not specific to a given EJB instance • Lacking for message-driven beans since they have no client-view

9. Overview of the Enterprise JavaBeans Model Interfaces and Classes Component interface • Provides remote client-side view of bean’s business methods • Extends javax.ejb.EJBObject thus providing methods to obtain access to Home interface and Primary Key classes and to test for equality between EJB instances • Lacking for message-driven beans since they have no client-view

10. Overview of the Enterprise JavaBeans Model Interfaces and Classes Implementation class • Implements one of the extensions of the javax.ejb.EnterpriseBean class which provide lifecycle notification methods (e.g., ejbPassivate) • javax.ejb.EntityBean • javax.ejb.SessionBean • javax.ejb.MessageDrivenBean • Class in which EJB developer codes the business methods defined in the bean’s component interface(s)

11. Overview of the Enterprise JavaBeans Model Interfaces and Classes Primary key class • Applicable only to entity beans • Uniquely differentiates one instance from the other instances sharing the same EJBHome • Class must be a legal value type in RMI-IIOP • Implements java.io.Serializable • Does not implement java.rmi.remote

12. Overview of the Enterprise JavaBeans Model Interfaces and Classes Exceptions • System exceptions are unchecked and propagate to the client as java.rmi.RemoteException • Application exceptions are checked and propagate to the client as a descendant of java.lang.Exception • EJB-specific exceptions include FinderException, CreateException, RemoveException (all in javax.ejb package) • Business method exceptions are at the discretion of the EJB developer

13. Overview of the Enterprise JavaBeans Model Interfaces and Classes Other interfaces and classes • Local interfaces used for access within server context (e.g., intercomponent calls, servlet invocation) • javax.ejb.EJBLocalHome • javax.ejb.EJBLocalObject • Interfaces for serializing EJB references • HomeHandle - reference to EJBHome • Handle - reference to EJBObject • EJBMetaData interface provides mechanism to gather information about the bean • Reference to EJBHome object • Home, component interface and primary key classes • Functions to determine bean type

14. Accessing Third-Party EJB Servers Agenda • Overview of the Enterprise JavaBeans (EJB) Model • PowerBuilder EJB client implementation • Coding a PowerBuilder EJB client application • Deploying PowerBuilder NVOs to EJB servers • Additional resources

15. PowerBuilder EJB Client Implementation Architecture Overview Feature overview • Uses Java Native Interface (JNI) for interoperability • Supports 1.0, 1.1, and 2.0 EJBs • Supports client-managed transactions • Supports system and application exception handling • Supplemented by EJB Proxy Generator • PowerBuilder IDE • EJB2PB90 command line utility

16. PowerBuilder EJB Client Implementation Architecture Overview Implementation overview • Built using the PowerBuilder Native Interface (PBNI) which allows developers to • Extend core features of PowerBuilder via custom C++ classes, and • Access PowerBuilder objects from other languages like C++, VisualBasic, and Delphi • Three PBNI classes are exposed in the PBEJBCLIENT90.PBD • JavaVM • EJBConnection • EJBTransaction • EJBLocator Java class, which wraps javax.naming.InitialContext, is contained in PBEJBCLIENT90.JAR • PowerBuilder proxy objects represent all other Java classes and interfaces required for a given EJB • JDK required for development, JRE for runtime – PowerBuilder installs Sun JDK 1.4 by default to ease configuration issues

17. PowerBuilder EJB Client Implementation Architecture Overview JavaVM object • Loads and initializes Java VM inside of the PowerBuilder process • Supported by configurable PowerBuilder ‘JVM Service’ which handles all JDK/JRE needs in PowerBuilder environment • JDBC Connectivity • EJB Client Functionality • JSP Deployment • XSL-FO • Be aware… • Once Java VM is loaded, for whatever reason, by PowerBuilder, you cannot modify its environment, classpath, etc.; use return value of CreateJavaVM to determine if Java VM was actually loaded or already resident • Debug option for CreateJavaVM method is not available for JDK 1.4 • Methods exist for determining the actual class for a returned interface, downcasting classes, determining interfaces implemented by classes, etc.

18. PowerBuilder EJB Client Implementation Architecture Overview PowerBuilder JVM Service configuration • JDK and JRE Location can be specified in System Options dialog • JVM properties and CLASSPATH entries are in the registry • Design-time: \\HKLM\Sybase\PowerBuilder\9.0\Java\PBIDEConfig • PBJVMConfig • PBJVMProps • PBSysClasspath • Run-time: \\HKLM\Sybase\PowerBuilder\9.0\Java\PBRTConfig • PBJVMConfig • PBJVMProps

19. PowerBuilder EJB Client Implementation Architecture Overview EJBConnection object • Analog of the PowerBuilder Connection object • Serves as a PowerBuilder façade to the InitialContext class within the PBEJBCLIENT90.JAR file • ConnectToServer - sets initialContext • DisconnectServer - closes initialContext • Lookup - returns EJBHome reference given JNDI name • GetEJBTransaction - returns reference enabling client-managed transactions • CreateJavaInstance – create a Java class within client Java VM • Be aware… • Properties array argument to ConnectToServer is the only ‘vendor-specific’ requirement; PowerBuilder doesn’t ‘know’ what EJB server you are using • CreateJavaInstance is used to create a Java class on the client – you don’t need an EJB server at all to do this!

20. PowerBuilder EJB Client Implementation Architecture Overview EJBTransaction object • Populated by GetEJBTransaction method of the EJBConnection object • Wraps javax.transaction.UserTransactionand so providesmethods for initiating, coordinating, and completing a transaction from a client application • BeginGetStatus • Commit SetRollbackOnly • Rollback SetTransactionTimeout • Be aware… • Not all EJB servers support client-managed transactions • Best practices have a session bean on the server controlling the transaction

21. PowerBuilder EJB Client Implementation Architecture Overview EJBLocator Java class • Single Java class residing in PBEJBCLIENT90.JAR:com.sybase.powerbuilder.ejb.EJBLocator • Four methods, all wrapped by the EJBConnection PBNI object • Required for deployed applications • JAR is included in CLASSPATH managed by JVM Service with the assumption that it is located relative to the PBJVM90.DLL

22. PowerBuilder EJB Client Implementation Architecture Overview PowerBuilder proxy objects • Used to delegate requests to and from the underlying Java classes • Inherited from Nonvisualobject or Exception class like other PowerBuilder proxies • Generated using javap command in JDK • EJB Client Proxy wizard / project in PowerBuilder development environment • EJB2PB90 stand-alone utility • Includes • Public methods defined on its associated Java class • Public class variables in PowerBuilder 9.0.1 and later • To avoid conflicts with PowerBuilder reserved words, names may be decorated • Proxy name prefix “java_”, for example, java_integer • Method name postfix ”_j”, for example, and_j • Java methods that return arrays will return any in PowerBuilder • Proxies are also supported by a PowerBuilder mapping structure that correlates the PowerBuilder proxy name to the underlying Java class name

23. PowerBuilder EJB Client Implementation Architecture Overview Sample source for a PowerBuilder proxy object $PBExportHeader$ejbobject.srx $PBExportComments$Proxy imported from EJB via EJB Proxy generator. global type EJBObject from Remote end type type variables protected: string EJBObject_javaname= "javax.ejb.EJBObject" end variables forward prototypes public: function EJBHome getEJBHome() throws RemoteException alias for "getEJBHome,()Ljavax/ejb/EJBHome;" function any getPrimaryKey() throws RemoteException alias for "getPrimaryKey,()Ljava/lang/Object;" subroutine remove() throws RemoteException, RemoveException alias for "remove,()V" function Handle getHandle() throws RemoteException alias for "getHandle,()Ljavax/ejb/Handle;” function boolean isIdentical( EJBObject EJBObject_1) throws RemoteException alias for "isIdentical,(Ljavax/ejb/EJBObject;)Z" end prototypes

24. Accessing Third-Party EJB Servers Agenda • Overview of the Enterprise JavaBeans (EJB) Model • PowerBuilder EJB client implementation • Coding a PowerBuilder EJB client application • Deploying PowerBuilder NVOs to EJB servers • Additional resources

25. Coding a PowerBuilder EJB Client Application • Setting up your environment • Adding the EJB client implementation to your target • Generating proxies • Basic client coding steps • Advanced topics

26. Coding a PowerBuilder EJB Client Application Setting Up Your Environment Adding the EJB Client implementation to your target • Include PBEJBCLIENT90.PBD in your target’s library list

27. Coding a PowerBuilder EJB Client Application Setting Up Your Environment Generating proxies • Use EJB Client Proxy Wizard EJB home interface name must be same as remote interface name followed by ‘Home’

28. Coding a PowerBuilder EJB Client Application Setting Up Your Environment Generating proxies • Use EJB2PB90.EXE, a completely stand-alone utility, and import resulting files into PowerBuilder target • Syntax: ejb2pb90 [-classpath pathlist] EJBName [prefix] • Output includes • Various .srx files – the proxy objects • ejbproxies.txt – listing the .srx files produced • ejbproxies.err – containing the diagnostic message in the event an error occurs while the proxies are generated • $EJBName$_ejb_pb_mapping.srs – the mapping structure

29. Coding a PowerBuilder EJB Client Application Basic client coding steps • Initialize the Java VM • Connect to the EJB Server • Lookup an EJB • Invoke methods on the EJB • Disconnect from the EJB Server

30. Coding a PowerBuilder EJB Client Application Basic Client Coding Steps Initialize the Java VM TRY g_JavaVM = CREATE JavaVM CHOOSE CASE g_JavaVM.CreateJavaVM(is_ClassPath, false) CASE 0 // JVM just loaded CASE 1 // JVM was already loaded, is_ClassPath ignored CASE -1 // failure, likely due to not finding JVM.DLL CASE -2 // failure, do to not finding EJBLocator class END CHOOSE CATCH (PBXRuntimeError prte) // catch any exception raised in PBNI extension END TRY

31. Coding a PowerBuilder EJB Client Application Basic Client Coding Steps Connect to the EJB Server TRY g_EJBConn = CREATE EJBConnection // set initial context properties ls_props[1] = "javax.naming.Context.INITIAL_CONTEXT_FACTORY=" + & "com.sybase.ejb.InitialContextFactory" ls_props[2] = "javax.naming.Context.PROVIDER_URL=iiop://localhost:9000" ls_props[3] = "javax.naming.Context.SECURITY_PRINCIPAL=jagadmin" ls_props[4] = "javax.naming.Context.SECURITY_CREDENTIALS=" // connect to EJB server g_EJBConn.connectToServer(ls_props) CATCH (NamingException ne) // naming exception may occur when initial context class not found CATCH (PBXRuntimeError prte) // catch any exception raised in PBNI extension END TRY

32. Coding a PowerBuilder EJB Client Application Basic Client Coding Steps Lookup an EJB TRY g_HelloHome = g_EJBConn.lookup("HelloHome", "PB9/Hello", "pb9.HelloHome") g_hello = g_helloHome.create() CATCH (NamingException ne) // raised if EJB not located CATCH (CreateException ce) // raised if problem in instantiating EJB CATCH (RemoteException re) // raised whenever there is a unchecked exception on server CATCH (PBXRuntimeError prte) // raised whenever there is an exception in the PBNI extension END TRY

33. Coding a PowerBuilder EJB Client Application Basic Client Coding Steps Invoke methods on the EJB TRY MessageBox("Hello", g_hello.sayHello() CATCH (YourCustomException yce) // handle user-defined exception raised by EJB, for example, an exception // indicating that an account lacks sufficient funds for withdrawal CATCH (RemoteException re) // raised whenever there is a unchecked exception on server CATCH (PBXRuntimeError prte) // raised whenever there is an exception in the PBNI extension END TRY

34. Coding a PowerBuilder EJB Client Application Basic Client Coding Steps Disconnect from the EJB server TRY g_EJBConn.disconnectServer() CATCH (NamingException ne) // naming exception is unlikely here, but could be thrown by underlying // Java InitialContext object CATCH (PBXRuntimeError prte) // raised whenever there is an exception in the PBNI extension END TRY As in many distributed processing scenarios, disconnecting a client does NOT automatically free server resources, such as stateful EJBs that the client was using.

35. Coding a PowerBuilder EJB Client Application Advanced topics • java.lang.Object references • Using interfaces and casting • Client-managed transactions • Creating proxies for stand-alone Java classes

36. Coding a PowerBuilder EJB Client Application Advanced Topics java.lang.Object references • Many EJB methods will return java.lang.Object references or expect them as parameters • PowerBuilder will treat a java.lang.Object reference as a PowerBuilder any variable within the method prototype • The mapping structure created when generating proxies is consulted at run-time to map the underlying Java class to an appropriate proxy global type Hello_ejb_pb_mapping from structure string item1 = "java.rmi.Remote:Remote" string item2 = "java.io.Serializable:Serializable" string item3 = "java.io.IOException:IOException" string item4 = "java.io.OutputStream:OutputStream" string item5 = "java.io.FilterOutputStream:FilterOutputStream" string item6 = "java.io.UnsupportedEncodingException:UnsupportedEncodingException" string item7 = "java.io.PrintStream:PrintStream" …

37. Coding a PowerBuilder EJB Client Application Advanced Topics Using interfaces and casting • Additional JavaVM object methods extend your capabilities • GetActualClass – determines the actual Java class name when provided a PowerBuilder proxy object that represents a Java interface • GetSuperClass – determines the Java class that is the ancestor of the Java class or interface represented by the PowerBuilder proxy object • GetInterfaces – returns list of Java interfaces implemented by the Java class represented by the given PowerBuilder proxy object • DynamicCast – casts a PowerBuilder proxy object to another object – typically used to downcast a Java reference, use cautiously since invalid casts can cause instability

38. Coding a PowerBuilder EJB Client Application Advanced Topics Using interfaces and casting – an example Collection px_Collection Vector px_Vector Stack px_Stack TRY px_ListMgr = px_ListMgrHome.create() px_Collection = px_ListMgr.getList(as_listType) CHOOSE CASE g_JavaVM.GetActualClass(px_Collection) CASE "java.util.Stack" px_Stack = g_JavaVM.DynamicCast(px_Collection, "Stack") DO WHILE TRUE this.processItem(px_Stack.pop()) LOOP CASE "java.util.Vector“ px_Vector = g_JavaVM.DynamicCast(px_Collection, “Vector”) FOR i TO px_Vector.size() this.processItem(px_Vector.elementAt(i)) NEXT ...

39. Coding a PowerBuilder EJB Client Application Advanced Topics Client-managed transactions • The EJBTransaction object in the PBNI implementation has a direct correspondence to javax.transaction.UserTransaction • Begin - starts a transaction • Commit - commits the current transaction • SetRollbackOnly - marks the current transaction as doomed • SetTransactionTimeout - sets the amount of time a transaction can be in progress before it is rolled back. • GetStatus - returns the status of the current transaction • Not all EJB servers support this and even if they do, best practices discourage its use

40. Coding a PowerBuilder EJB Client Application Advanced Topics Client-managed transactions – an example EJBConnection conn EJBTransaction trans conn = create EJBConnection TRY conn.connectToServer(is_props) trans = conn.getEJBTransaction() trans.Begin() // Create a component and call methods to be // executed within the transaction trans.Commit() CATCH (Exception e) trans.Rollback() END TRY

41. Coding a PowerBuilder EJB Client Application Advanced Topics Creating proxies for stand-alone Java classes • You can use the EJB client implementation to call Java classes on the client as well! • Create ‘dummy’ home and remote interface Java classes and reference the desired Java class as a method argument or return value • Generate proxies for this ‘pseudo’ EJB and the proxies for the referenced classes will be automatically generated • Now use the CreateJavaInstance method of the EJBConnection object to create instances of your Java class on the client (you can do this without issuing a ConnectToServer) Dummy Home interface Java code Dummy Home interface Java code public interface DummyHome {} public interface Dummy { public abstract void foo(com.your.JavaClass x); }

42. Accessing Third-Party EJB Servers Agenda • Overview of the Enterprise JavaBeans (EJB) Model • PowerBuilder EJB client implementation • Coding a PowerBuilder EJB client application • Deploying PowerBuilder NVOs to EJB servers • Additional resources

43. Deploying PowerBuilder NVOs to EJB Servers Sunlly Group’s PBridge (http://www.sunlly.com) • Since PowerBuilder 7, you can use PowerBuilder NVOs natively in EAServer and have them interoperate with EJB components and Java clients • Sunlly PBridge’s offering will allow you to deploy your PowerBuilder components into other application servers such as WebLogic and WebSphere • Built on PBNI architecture offered by PowerBuilder 9 • Currently in beta and supporting • BEA WebLogic • IBM WebSphere • Sun J2EE reference implementation • Visit them at TechWave!

44. Deploying PowerBuilder NVOs to EJB Servers Sunlly PBridge – Client Deployment Interface

45. Accessing Third-Party EJB Servers Agenda • Overview of the Enterprise JavaBeans (EJB) Model • PowerBuilder EJB client implementation • Coding a PowerBuilder EJB client application • Deploying PowerBuilder NVOs to EJB servers • Additional resources

46. Accessing Third-Party EJB Servers Additional Resources InitialContext classes and default URLs for major EJB servers

47. Accessing Third-Party EJB Servers Additional Resources Learning more about the EJB client feature • PowerBuilder Extension Reference in product documentation set • EJB specification (http://java.sun.com/products/ejb/docs.html) • 3rd party J2EE server web sites • BEA Systems WebLogic Server (http://www.bea.com/framework.jsp?CNT=index.htm&FP=/content/products/platform/) • Jboss (http://www.jboss.org) • IBM WebSphere Application Server (http://www.ibm.com/websphere) • Oracle9iAS (http://http://www.oracle.com/ip/deploy/ias/) • SAMS Publishing PowerBuilder: Internet and Distributed Application Development (http://www.pb9book.com) • Sybase Developer Network (http://sdn.sybase.com) • Technical document: “Accessing 3rd Party EJB Servers from PowerBuilder 9” (http://www.sybase.com/detail?id=1024977) • CodeXchange…

48. SDN Presents CodeXchange Share PowerBuilder 9 Code and Tools • New SDN feature enables community collaboration • Download samples created by Sybase • Leverage contributions of others to exploit PBNI (i.e. PBNI CommonDialog, PBNI OLEObject utilities) • Contribute your own code or start your own collaborative project with input from other PowerBuilder experts • Any SDN member can participate • Log in using your MySybase account via SDN • Join the collaboration already underway • http://powerbuilder.codexchange.sybase.com or via SDN at www.sybase.com/developer • SDN & CodeXchange at TechWave • Technology Boardwalk • Sybase Booth Theater

49. Accessing Third-Party EJB Servers Questions