PWB519 Accessing ThirdParty Enterprise JavaBeans Servers from PowerBuilder 9.0

1
PWB519 Accessing Third-Party Enterprise JavaBeans
Servers from PowerBuilder 9.0
Jim ONeilPrincipal Technical Support
EngineerSybase, Inc. (Concord,
MA)joneil_at_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 Suns 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 beans
  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 beans 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\P
  BIDEConfig
• PBJVMConfig
• PBJVMProps
• PBSysClasspath
• Run-time \\HKLM\Sybase\PowerBuilder\9.0\Java\PBRT
  Config
• 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 doesnt know what EJB server you
  are using
• CreateJavaInstance is used to create a Java class
  on the client you dont 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.UserTransaction and so
  provides methods 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.JARc
  om.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 PBExportHeaderejbobject.srx PBExportComm
entsProxy 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" subroutin
e 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,(Lja
vax/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 targets
  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)

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_props1 "javax.naming.Context.INITIAL_CONTE
  XT_FACTORY"
• "com.sybase.ejb.InitialContextFactory"
• ls_props2 "javax.naming.Context.PROVIDER_URL
  iiop//localhost9000"
• ls_props3 "javax.naming.Context.SECURITY_PRIN
  CIPALjagadmin"
• ls_props4 "javax.naming.Context.SECURITY_CRED
  ENTIALS"
• // 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)

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.RemoteRemote"
string item2 "java.io.SerializableSerializabl
e" string item3 "java.io.IOExceptionIOExceptio
n" string item4 "java.io.OutputStreamOutputStr
eam" string item5 "java.io.FilterOutputStreamF
ilterOutputStream" string item6
"java.io.UnsupportedEncodingExceptionUnsupportedE
ncodingException" string item7
"java.io.PrintStreamPrintStream"
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))

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 Groups 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 PBridges 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/ej
  b/docs.html)
• 3rd party J2EE server web sites
• BEA Systems WebLogic Server (http//www.bea.com/fr
  amework.jsp?CNTindex.htmFP/content/products/pla
  tform/)
• 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.co
  m/detail?id1024977)
• 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