E173 Invoking Enterprise Java Beans From PowerBuilder

1
E173 Invoking Enterprise Java Beans From
PowerBuilder

• Jim ONeil
• Principal Technical Support Engineer
• Enterprise Solutions Division
• joneil_at_sybase.com

2
Invoking Enterprise Java Beans From PowerBuilder

• Agenda
• Overview of the Enterprise Java Bean (EJB) Model
• Implementation of EJB client functionality
• Architecture overview
• Demo (with supporting slides)
• Additional resources
• EJB server vendor-specific requirements
• Learning more about the EJB client feature

3
Invoking Enterprise Java Beans From PowerBuilder

• Overview of the Enterprise Java Bean Model
• Core concepts
• EJB types
• Interfaces and classes
• Exceptions
• The view from a client

4
Overview of the Enterprise Java Bean 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 Java Bean Model

• 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 Java Bean Model

• Interfaces and classes
• Home interface
• Component interface
• Local interfaces
• Implementation class
• Primary key class
• Supporting interfaces

7
Overview of the Enterprise Java Bean
ModelInterfaces and Classes

• Home interface
• Provides remote client-view of methods affecting
  the EJB lifecycle
• Extends javax.ejb.EJBHome
• With EJB 2.0, can include business methods that
  are not specific to a given EJB instance
• Lacking for message-driven beans since they have
  no client-view

8
Overview of the Enterprise Java Bean
ModelInterfaces 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

9
Overview of the Enterprise Java Bean
ModelInterfaces and Classes

• Local interfaces
• Interfaces (home and component) used by clients
  within the same Java Virtual Machine (VM) as the
  EJB
• javax.ejb.EJBLocalHome
• javax.ejb.EJBLocalObject
• Benefits lie in faster access and the less
  complex programming possible due to lack of a
  network layer
• Primary drawback is the tight-coupling of the
  client to the component thus eliminating location
  independence and reducing options for
  redistribution

10
Overview of the Enterprise Java Bean
ModelInterfaces 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 Java Bean
ModelInterfaces 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
• Does not result in Java-gtIDL name collisions

12
Overview of the Enterprise Java Bean
ModelInterfaces and Classes

• Supporting interfaces
• 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

13
Overview of the Enterprise Java Bean Model

• 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

14
Overview of the Enterprise Java Bean Model

• The view from a client

EJB Container (Server)
Client
15
Invoking Enterprise Java Beans From PowerBuilder

• Implementation of EJB client functionality
• Feature and implementation overview
• Supporting PowerBuilder classes
• Client coding steps (Demo)
• Advanced topics
• Handling exceptions
• Accessing message-driven beans
• Client-managed transactions

16
Invoking Enterprise Java Beans From PowerBuilder

• Implementation of EJB client functionality

17
Implementation of EJB Client Functionality

• 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
• EJB2PB command line utility

18
Implementation of EJB Client Functionality

• Implementation overview
• Built using the new 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
• For much more detail on PBNI see session E175
  Introduction to PowerBuilder Native Interface

19
Implementation of EJB Client Functionality

• Supporting PowerBuilder classes
• Eight PBNI classes are exposed as custom class
  user objects in the PBEJBCLIENT90.PBD (and DLL)
  delivered with PowerBuilder 9
• JavaVM gt EJBTransaction
• EJBConnection gt EJBMetaData
• EJBHome gt EJBHomeHandle
• EJBObject gt EJBHandle
• The PBD is added to the targets library list and
  the DLL placed somewhere in the system PATH

20
Implementation of EJB Client FunctionalityPBEJBCL
IENT90.PBD Classes

• JavaVM
• Loads and initializes Java VM inside of the
  PowerBuilder process
• Prerequisite for EJB access
• Only one Java VM can be loaded for duration of
  process
• Java VM reference variable in PowerBuilder would
  generally be an instance variable of a singleton
  NVO or a global variable, depending on the
  applications partitioning

21
Implementation of EJB Client FunctionalityPBEJBCL
IENT90.PBD Classes

• EJBConnection
• EJB client analog of the PowerBuilder connection
  object used for CORBA access to EAServer
• ConnectToServer - sets initialContext given
  ContextFactory class, URL and user credentials
• DisconnectServer - closes initialContext
• Lookup - returns EJBHome reference given JNDI
  name
• GetEJBTransaction - returns reference enabling
  client to manage transaction
• CreateJavaInstance - creates Java class instance
  to support EJB methods (e.g., primary key class)

22
Implementation of EJB Client FunctionalityPBEJBCL
IENT90.PBD Classes

• EJBHome
• Ancestor of home interface classes created by the
  PowerBuilder EJB Proxy wizard and the EJB2PB
  command line utility
• Wraps methods of javax.ejb.EJBHome
• GetHomeHandle
• GetEJBMetaData
• Remove
• Proxies will also be generated for HomeHandle and
  EJBMetaData

23
Implementation of EJB Client FunctionalityPBEJBCL
IENT90.PBD Classes

• EJBObject
• Ancestor of remote component interface classes
  created by the PowerBuilder EJB Proxy wizard and
  the EJB2PB command line utility
• Wraps methods of javax.ejb.EJBObject
• GetEJBHome gt IsIdentical
• GetHandle gt Remove
• GetPrimaryKey
• Proxies will also be generated for Handle and
  Object

24
Implementation of EJB Client FunctionalityPBEJBCL
IENT90.PBD Classes

• EJBTransaction
• Populated by GetEJBTransaction method of the
  EJBConnection object
• Wraps javax.transaction.UserTransaction and so
  provides methods for initiating, coordinating,
  and completing a transaction from client
  application
• Begin gt GetStatus
• Commit gt SetRollbackOnly
• Rollback gt SetTransactionTimeout

25
Implementation of EJB Client FunctionalityPBEJBCL
IENT90.PBD Classes

• EJBMetaData
• Populated by EJBHome.GetEJBMetaData method
• Wraps javax.ejb.EJBMetaData providing methods to
  dynamically determine the EJB implementation
• GetHomeInterfaceClass
• GetPrimaryKeyClass
• GetRemoteInterfaceClass
• GetEJBHome
• IsSession
• IsStatelessSession

26
Implementation of EJB Client FunctionalityPBEJBCL
IENT90.PBD Classes

• EJBHomeHandle
• Populated by EJBHome.GetHomeHandle method
• Wraps javax.ejb.HomeHandle providing a mechanism
  to serialize the reference to an EJB home
  interface for later use
• GetEJBHome method converts from HomeHandle back
  to a home interface reference (EJBHome)

27
Implementation of EJB Client FunctionalityPBEJBCL
IENT90.PBD Classes

• EJBHandle
• Populated by EJBObject.GetHandle method
• Wraps javax.ejb.Handle providing a mechanism to
  the serialize reference to an EJB instance for
  later use
• GetEJBObject converts from Handle back to a
  remote component interface reference (EJBObject)

28
Implementation of EJB Client Functionality

• Client coding steps
• Get EJB stubs and other required client classes
  from EJB server
• Setup Java environment
• Add EJB PBNI classes to PowerBuilder target
• Generate PowerBuilder proxies for EJB
• Code the client application accessing the EJB

29
Implementation of EJB Client FunctionalityClient
Coding Steps

• Get EJB stubs and other required client classes
  from EJB server
• Each vendor has client classes required in the
  CLASSPATH (e.g., weblogic.jar for BEA WebLogic)
• Since this is a JNI implementation, the Java stub
  classes for the EJB are also required.
  Instructions for generating and compiling those
  stubs will also be detailed by the EJB server
  vendor. With EAServer, for example, you would
  use Jaguar Manager.

30
Implementation of EJB Client FunctionalityClient
Coding Steps

• Setup Java environment
• Set the JAVA_HOME environment variable to the
  directory containing the JDK
• Make sure jvm.dll is in the path (the file is
  usually located in JAVA_HOME/jre/bin/classic)
• Ensure correct operation of javap (which is used
  for generation of proxies)
• javap.exe is usually in JAVA_HOME/bin
• javax.ejb classes must be in CLASSPATH

31
Implementation of EJB Client FunctionalityClient
Coding Steps

• Add EJB PBNI classes to PowerBuilder target
• Add PBEJBCLIENT90.PBDto your PowerScript
  targets library list
• Ensure that PBEJBCLIENT90.DLL is in your PATH
• Ensure that PBEJBCLIENT90.JAR is in your
  CLASSPATH

32
Implementation of EJB Client FunctionalityClient
Coding Steps

• Generate proxies for EJB
• PowerBuilder uses proxies that wrap the EJB
  stubs as well as any intermediary Java classes
  that may be required
• EJB Client Proxy Wizard
• EJB2PB command line utility

33
Implementation of EJB Client FunctionalityClient
Coding Steps

• Generate proxies for EJB via IDE

34
Implementation of EJB Client FunctionalityClient
Coding Steps

• Generate proxies for EJB via EJB2PB
• EJB2PB.EXE is a command-line program found in the
  Shared/PowerBuilder folder
• EJB2PB -classpath pathlist EJBName prefix
• pathlist - optional extension to system CLASSPATH
  for finding EJBName class
• EJBName - remote component interface class name
• prefix - optional prefix for proxies
• Output is two or more .srx files which can then
  be imported into a PowerScript target

35
Implementation of EJB Client FunctionalityClient
Coding Steps

• Code the client application accessing the EJB
• Create Java VM
• Connect to EJB server
• Look up EJBs home interface
• Access EJBs remote component interface
• Call business method(s)
• Disconnect from EJB server

36
Implementation of EJB Client FunctionalityClient
Coding Steps

• Create the JavaVM
• Define JVM reference variable as a global
  variable JavaVM gJVM
• Declare properties array and classpath variables
• string props - arguments to JAVA.EXE command
  line (analogous to Java Properties)
• string classpath - additional classes to be
  appended to system CLASSPATH prior to starting
  the Java VM

37
Implementation of EJB Client FunctionalityClient
Coding Steps

• Create the JavaVM
• Create Java VM reference
• long llRet
• llRet gJVM.createJavaVM(classpath, props)
• IF (llRet ltgt 0) THEN
• MessageBox("Failed to Create JavaVM",
• "Return Code " String(llRet),
• StopSign!)
• END IF

38
Implementation of EJB Client FunctionalityClient
Coding Steps

• Connect to EJB server
• Create an EJBConnection instance
• EJBConnection lcWebsphere
• lcWebsphere CREATE EJBConnection
• Initialize required connectivity properties
• string props
• props1 "javax.naming.Context.INITIAL_CONTEXT_F
  ACTORYweblogic.jndi.WLInitialContextFactory"
• props2 "javax.naming.Context.PROVIDER_URLt3
  //localhost7001"

39
Implementation of EJB Client FunctionalityClient
Coding Steps

• Connect to EJB server
• Connect to the server
• TRY
• lcWebsphere.connectToServer(props)
• CATCH (Exception e1)
• MessageBox("Connection Exception",
  e1.getMessage(), StopSign!)
• END TRY

40
Implementation of EJB Client FunctionalityClient
Coding Steps

• Lookup EJBs home interface
• TraderHome lejbHome // EJB Home proxy
• TRY
• lejbHome lcWebsphere.lookup("TraderHome",
  "statelessSession.TraderHome",
• "examples.ejb11.basic.statelessSession. TraderH
  ome")
• CATCH (NamingException e2)
• MessageBox("Lookup Failed", e2.getMessage
  ())
• CATCH (Throwable e3)
• MessageBox("Other Error", e3.getMessage())
• END TRY

41
Implementation of EJB Client FunctionalityClient
Coding Steps

• Access EJBs remote component interface
• Trader lejbObject // EJB proxy TRY
• lejbObject lejbHome.ejbCreate()
• CATCH (CreateException e4)
• MessageBox(EJB Creation Failed", e4.getMessa
  ge())
• CATCH (Throwable e5)
• MessageBox(Other Error", e5.getMessage())
• END TRY

42
Implementation of EJB Client FunctionalityClient
Coding Steps

• Call business method(s)

TradeResult lnvRet // Java class
proxy TRY lnvRet lejbObject.buy("SY",
1000) MessageBox(Purchase Info", "Purchase
of " String(lnvRet.getNumberTraded()) "
shares of " lnvRet.getStockSymbol() "
was successful!") CATCH (Throwable
e6) MessageBox(Unexpected Error",
e6.getMessage()) END TRY
43
Implementation of EJB Client FunctionalityClient
Coding Steps

• Disconnect from EJB server
• lcWebsphere.disconnectServer()

As in most distributed processing
scenarios,disconnecting from the client does not
automatically free server resources and could
result in orphaned instances!
44
Implementation of EJB Client FunctionalityAdvance
d Topics

• Handling exceptions
• EJB client capability requires heavy use of the
  TRY-CATCH-FINALLY construct in PowerScript
• Java exceptions raised from EJBs extend
  java.lang.Exception (with few exceptions)
• Client proxies wrapping system exceptions like
  java.rmi.RemoteException, etc. extend the
  PowerBuilder core Exception class
• Application exceptions thrown by EJBs are
  likewise handled by PowerBuilder Exception class
  proxies

45
Implementation of EJB Client FunctionalityAdvance
d Topics

• Accessing message-driven beans
• Message-driven beans have no client view
• No home or component interfaces
• No direct invocation mechanism from a client
• Message-driven beans listen to messages
  delivered by the Java Message Service (JMS)

46
Implementation of EJB Client FunctionalityAdvance
d Topics

• Accessing message-driven beans
• A PowerBuilder client can send a JMS message to a
  listening message-driven bean
• Via the CORBA layer to EAServers Message Service
• Via HTTP using PowerBuilders PostURL function to
  invoke a servlet that publishes a JMS message
• Via JNI
• Via 3rd party tools like JMSCourier

47
Implementation of EJB Client FunctionalityAdvance
d Topics

• Client-managed transactions
• EJBTransaction wraps the functionality of
  javax.transaction.UserTransaction providing a
  complete implementation of the Java interface
  (http//java.sun.com/products/jta)
• PowerBuilder can thus serve as the controller of
  a transaction involving bean-managed EJBs versus
  requiring a coordinator EJB on the server to
  which the client delegates the handling of the
  transaction

48
Implementation of EJB Client FunctionalityAdvance
d Topics

• Client-managed transactions
• Obtain reference to the transaction
• EJBConnection conn
• EJBTransaction trans
• string properties
• conn create EJBConnection
• TRY
• conn.connectToServer(props)
• trans conn.getEJBTransaction()
• CATCH (Exception e)
• ...
• END TRY

49
Implementation of EJB Client FunctionalityAdvance
d Topics

• Client-managed transactions
• Manage the transaction from the client
• TRY
• trans.Begin()
• // Create a component and call methods to be
• // executed within the transaction
• ...
• // Commit the transaction
• trans.Commit()
• CATCH (Exception e)
• trans.Rollback()
• END TRY

50
Invoking Enterprise Java Beans From PowerBuilder

• EJB server vendor-specific requirements
• In addition to Sybase EAServer, PowerBuilder 9.0
  is tested against
• BEA Systems, Inc. WebLogic Server
• IBM WebSphere
• There is, however, nothing in the implementation
  to preclude connecting to any other J2EE
  compliant application server

51
Invoking Enterprise Java Beans From PowerBuilder

• EJB server vendor-specific requirements
• To use PowerBuilder 9.0s EJB client feature,
  some vendor-specific information is required to
  make the connection to the target EJB server
• Initial context class
• Provider URL format
• Supporting classes required on the client machine
• Subsequent slides detail specifics for the major
  J2EE server vendors (URL format includes default
  values)

52
EJB Server Vendor-Specific Requirements

• EAServer
• Initial context com.sybase.ejb.InitialContextFac
  tory
• URL format iiop//localhost9000
• Supporting classes easclient.jar easj2ee.jar

You can access EJBs on EAServer with PowerBuilder
8 on EAServer using the standard connection
object (which utilities EAServers ORB to connect
to the server)
53
EJB Server Vendor-Specific Requirements

• WebLogic Server
• Initial context weblogic.jndi.WLInitialContextFa
  ctory
• URL format t3//localhost7001
• Supporting class weblogic.jar

54
EJB Server Vendor-Specific Requirements

• IBM
• Initial context com.ibm.websphere.naming. WsnI
  nitialContextFactory
• URL format iiop//localhost900
• Supporting classes include weblogic.jar and
  others obtained from the WebSphere Application
  Client CD that ships with the J2EE server
• Note that WebSphere relies on the IBM Java VM not
  Suns

55
EJB Server Vendor-Specific Requirements

• ONE Application Server (formerly
  Application Server)
• Initial context com.sun.jndi.cosnaming.CNCtxFact
  ory
• URL format iiop//localhost9010
• Supporting classes javax.jar iasclient.jar
• Additional ORB configuration may also be required
  when invoking from remote clients

56
EJB Server Vendor-Specific Requirements

• Initial context org.jnp.interfaces.NamingContext
  Factory
• URL format jnp//localhost1099
• Supporting classes are located in the client
  subdirectory of the J2EE server installation and
  include as a minimum
• jnp-client.jar gt jboss-client.jar
• jnet.jar gt jboss-j2ee.jar

57
Invoking Enterprise Java Beans From PowerBuilder

• Learning more about the EJB client feature
• EJB specification available at Suns web site
• 3rd party J2EE server web sites
• Participate in the PowerBuilder 9.0 Beta!
• Sybase Developer Network (SDN)

58
Invoking Enterprise Java Beans From PowerBuilder

• Sybase Developer Network (SDN)
• Single point of access to developer software,
  services, and up-to-date technical information
• White papers and documentation
• Collaboration with other developers and Sybase
  engineers
• Code samples and beta programs
• Technical recordings
• Free software
• Join today www.sybase.com/developer or visit
  SDN at TechWaves Technology Boardwalk

59
Invoking Enterprise Java Beans From PowerBuilder

• Questions