Transcript Presentation Title Goes Here Arial 30 pts

Using the PowerBuilder
Application Server Plugin
Alex Pratt
Systems Consultant
Sybase EMEA
[email protected]
Prelude
Enable PowerBuilder for Distributed/Web Applications has been high
on the agenda in the last 10 years.
There have been many solutions or frameworks developed or
supported by Sybase.
Most of these solutions require Sybase EAServer.
Cost, Market pressure,… made life for a PowerBuilder developer
tough. ( ie. Corporate decision to use WebLogic as J2EE
container).
Productivity, Agility rely on the the portability and re-use of
legacy/existing code.
Prelude
Different methods to go n-tier :
- Rewrite to Java/Javascript for both
- Labor intensive
- Risky
- Platform/infrastructure independent
- Use EAServer; requires application partitioning
- Older applications require refactoring
- UI needs to be rewritten but not the business logic
- PowerBuilder Appeon a ‘converter’
-
Supports both business logic and user interface
Rich Web UI
95% of PB code supported
Requires EAServer
Cost
- PB 11 .Net Webforms
-
Supports business logic and user interface
Rich Web UI
90-95% of PB code supported
Low cost
Requires IIS
Prelude
There was room for a solution that allows:
- Deploying PowerBuilder logic in different containers
(J2EE)
- Preserved the investment made into PB code and
allowed to continue use PB in J2EE projects.
- Enables the use of open source infrastructure.
- Integrated into “SOA philosophy” ( support for
webservices…)
The PowerBuilder Application Server Plugin answers
these requirements
PowerBuilder Application Server Plugin
 What is it?
 Platforms
 IDE Integration
 Installation
 Configuration
 Development
 Deployment
 Debugging
 Security
 Troubleshooting
 Licensing, Pricing, Release…
What is it?
 A Deployment Tool that wraps PowerBuilder NVOs as EJB
Session Beans (optionally as J2EE 1.4 Web Services) for
deployment into a J2EE 1.3+ compliant application server.
 A Server Runtime Library that integrates the PowerBuilder Virtual
Machine with the EJB container and transaction and connection
managers of the application server.
 A Remote Debugging Component that permits debugging from the
PowerBuilder IDE.
 A Web DataWindow Component that permits browser-based
clients to utilize DataWindow functionality.(certified in v1.x)
 A Proxy Server that permits PB clients to call deployed PB NVOs
without the use of a client side Java virtual machine. Also permits
PB clients and components to call “pure” EJBs.
Architecture Diagram
Client
PB Client
Server
Proxy Server
Application Server
EJB Client
EJB Container
PB Components
(EJB Session Beans)
Web Container
Web Client
PowerBuilder VM
Server Runtime
Library (Java, C++)
Developer
PowerBuilder
IDE
Deployment Tool
(Jaguar Compiler)
Remote Debugging
Component
(EJB Web Services)
Web DataWindow
Component
Supported Application Servers
 JBoss 4.0.4
 WebLogic 9.2
 WebSphere 6.1
 Geronimo (but not in initial release)
Supported Operating Systems
 Development environment
• Windows (PowerBuilder IDE)
 Server runtime environment
• Windows (2000, 2003, XP)
• Solaris (after initial release…NOT YET!!)
• Linux (after initial release…NOT YET!!)
Supported PowerBuilder Versions
 10.5.1+
 You might find that 10.0+ releases before 10.5.1 work,
but they will not be officially “supported”, and they will
not be QA certified.
PowerBuilder IDE Integration
 The deployment tool runs on your application server
machine, and emulates the Sybase EAServer PB NVO
deployment API.
 To create a component (in PowerBuilder IDE)
• New -> Target -> Application Server Component, or
• New -> Project -> Application Server Component, or
• New -> Project -> Application Server Component Wizard
 To deploy a component (in project painter)
• “Deploy Button”, or Design -> Deploy Project
PowerBuilder IDE integration
Installation
 The PB Server Plugin is installed on the application
server host.
 This does not need to be the same machine where the
PowerBuilder IDE is running.
 The PowerBuilder VM must also be installed on the
application server host. The plugin installer will take
care of this.
(you can also use the Runtime packager to install the
PowerBuilder components necessary)
Installation - Continued
 Default installation directory (Windows)
• c:\Program Files\Sybase\PBServer
 If you have a new or updated copy of the plugin in a
JAR or ZIP archive, just extract into the selected
installation directory.
 (Optional) Define system level environment variable
PB_SERVER_HOME to refer to this directory.
 You can install multiple copies on a machine, each copy
in a separate installation directory.
Configuration - General
 The PB server plugin is configured on the application
server host.
 Configuration uses:
• Batch files (Windows)
• Shell scripts (Unix), with file extension “.sh”
• Ant XML scripts (all platforms)
 To customize, edit the XML scripts.
 Shut down your application server before running
configuration tasks.
 Ensure that file bin\set-java-home.bat refers to the JDK
used by your application server.
Configuration - JBoss
 Run the following commands (Windows)
• cd %PB_SERVER_HOME%
• bin\set-admin-password
• bin\configure pb-server-jboss
–Djboss.home=jboss-home-dir
 To customize the configuration XML scripts edit:
• config\ejb-proxy-jboss.xml
• config\pb-server-jboss.xml
 If you edit an XML script, re-run the above ‘configure’
command. Hint: check if the scripts require editing
before running ‘configure’ for the first time.
Demo
Step 1: all the components are installed ( PASP, JBOSS,
JDK)
Step 2: set-java-home.bat adjustments ( we are using the
jdk 1.5)
Step 3: set-admin-password.bat ( only if you have not
done this during the install)
Step 4: check that pb-server-jboss.xml and ejb-serverjboss.xml are adapted.
Step 5: run
configure.bat pb-server-jboss « -Djboss.home=c:\jboss-4.0.4.GA »
C:\PBAppServer1\bin>configure.bat pb-server-jboss "-Djboss.home=c:\jboss-4.0.4.GA«
Buildfile: C:\PBAppServer1\bin\..\config\pb-server-jboss.xml
configure:
configure-server-onetime:
configure-server-onetime-tasks:
[mkdir] Created dir: C:\PBAppServer1\genfiles\jboss
[jar] Building jar: C:\jboss-4.0.4.GA\server\default\lib\init-pb-server.jar
[copy] Copying 1 file to C:\jboss-4.0.4.GA\server\default\lib
[copy] Copying 1 file to C:\jboss-4.0.4.GA\server\default\lib
[copy] Copying 1 file to C:\jboss-4.0.4.GA\server\default\deploy
configure-client-onetime:
[copy] Copying 2 files to C:\PBAppServer1\lib
configure-proxy:
configure:
configure-pb-server-test:
BUILD SUCCESSFUL
Total time: 12 seconds
Server Startup - General
 When starting your server, the following must be ensured.
• Java system property pb.server.home refers to the plugin
installation directory.
• %PB_SERVER_HOME%\lib\pb-server-(14 or 15).jar is in the
CLASSPATH or otherwise shared by all deployed applications in
the JVM (most of the provided scripts take care of this)
• %PB_SERVER_HOME%\lib is in the system PATH or
java.library.path.
• Your PowerBuilder directory containing pbvmXXX.dll or
libpbvmXXX.* is in the system PATH (Windows),
LD_LIBRARY_PATH (Solaris), etc.
• Environment variable JAGUAR is set to plugin install dir.
• Enviromnent variable JAGSSL is set to true.
Generated Startup Script
 The configuration task creates a batch / script file that
can be used to start your server with the necessary
options. It will start your server assuming a “standard”
installation of your server.
 The generated batch/script file can be used as a sample
that you can use to determine what needs to be done
before startup for the plugin to work with your server.
• bin\start-jboss.*, run-jboss.*
• bin\start-weblogic.*
• bin\start-websphere.*
 You should probably consult your application server
administrator to determine the best startup script.
Lets do it!!!
C:\PBAppServer1\bin>start-jboss.bat
C:\PBAppServer1\bin>
start "JBoss" "C:\PBAppServer1\bin\..\bin\run-jboss.bat »
If it is the first time make sure you see these lines in the console or the pbserver.log
 15:44:40,823 INFO [STDOUT] Compiling: BCD.idl
 15:44:41,120 INFO [STDOUT] Compiling: MJD.idl
 15:44:41,198 INFO [STDOUT] Compiling: CTS.idl
 15:44:41,229 INFO [STDOUT] Compiling: XDT.idl
 15:44:41,823 INFO [STDOUT] Compiling: CtsComponents.idl
 15:44:43,011 INFO [STDOUT] Compiling: CtsServices.idl
 15:44:43,073 INFO [STDOUT] Compiling: TabularResults.idl
 15:44:43,417 INFO [STDOUT] Compiling: CosNaming.idl
 15:44:43,526 INFO [STDOUT] Compiling: DataWindow.idl
 15:44:43,745 INFO [STDOUT] Compiling: SessionManager.idl
Deployment – JBoss Notes
 Ensure that automatic deployment is enabled.
• http://wiki.jboss.org/wiki/Wiki.jsp?page=ConfiguringTheDeplo
ymentScannerInConfjbossSystem.xml
• Make sure that the ScanEnabled attribute is not set to false.
 Note: automatic redeployment doesn’t always seem to work
properly with JBoss, when tested by Sybase.
• You may need to restart JBoss after deployment, to pick up your
changes.
Development – Components
 Develop components as if you were writing NVOs for
deployment to Sybase EAServer.
 Check the PowerBuilder documentation for general
instructions.
 The deployment tool will wrap your PB NVOs as
standard EJB session beans.
 Target-specific deployment descriptors are generated to
automate the binding of JNDI names and JDBC data
source resource references.
Development – Data Sources
 PowerScript (in NVO source code):
sqlca.dbms = “JDBC”
sqlca.dbparm =
connect;
//
...
//
disconnect; //
“CacheName=’MyCache’”(I use SybaseDB)
check error code
use embedded SQL or DataStore
check error code
 Whatever “cache names” you use in your code must be mapped to
application server “data source” names.
Development – Data Sources
 %PB_SERVER_HOME%\config\pb-server-XXX.xml must be edited to
map PB “cache names” to app. server “data source” JNDI names. Rerun the “configure” command afterwards.
 Add -Dcom.sybase.jaguar.jcm=true to the java options of the
application server to get more debug info on the connection cache in
the pb-server.log file.
 Remember you need to add the jdbc-driver.jar to
%jboss_home%\server\default\lib
16:55:39,328ERROR[STDERR]
com.sybase.powerbuilder.jdbc.PbjdbcJagCache.GetConnectionFromJaguar(PbjdbcJagCache.java:297)
And add reference to it in pb-server.jboss.xml
Development – Native Data Sources
 We support Sybase, Oracle, Oracle Unicode, ODBC,.
ODBC Unicode. We have a “fake” JDBC driver for each
data source type. The application server doesn’t realize
it is managing native connections!
 Check the documentation for full details.
 Basic steps (in addition to those on previous page) are:
• (PowerScript Code) Set the sqlca.dbms, e.g.
– sqlca.dbms = “SYJ” // Sybase Native
• (App. Server Config) Define your application server data
source to use the appropriate “fake” JDBC driver class, e.g.
– com.sybase.jaguar.jcm.sybase.SybaseDriver
• (App. Server Config) Set the connection URL, e.g.
– jdbc:sybase:jcm:sybase:databaseName=MyDB;user=xx;password=yy
Development – Data Types
 PowerBuilder data types are mapped to Java data types in the
generated EJB remote interface. Check docs for full details.
 Basic types:
• PB: Boolean, Char, Byte, Integer, Long, LongLong, Real, Double, Decimal
• Java: boolean, char, byte, short, int, long, float, double, java.math.BigDecimal
 Other types:
• PB: Blob, String, Date / Time / DateTime, ResultSet
• Java: byte[], String, java.util.Calendar, java.sql.ResultSet
 PB structures map to Java serializable classes with public fields.
 PB variable-sized arrays map to Java arrays, don’t use PB fixed
size arrays.
 Don’t use “by reference” parameters, all results must be by the
“return” type. You may need to return PB structures.
Development – Null Values
 If you want to propagate null values, you need to use
the “XDT” data types.
• XDT_IntValue maps to java.lang.Integer.
• XDT_LongValue maps to java.lang.Long.
• You get the idea!
 To generate the “XDT” data types, use the “Application
Server Proxy” wizard to generate proxies for package
“XDT”. It may be useful to save these generated types
in a PBL for convenient reuse in multiple projects.
 Each “XDT” type has a ‘value’ field and an ‘isNull’ field.
Set ‘isNull’ to true to propagate a null value.
Development – DataStore Type
 The PB DataStore type, in combination with the PB
ResultSet return type, is particularly useful for PB NVOs
running in an application server.
 You should use DataStore only internally within your
component.
 For improved performance, use PB NVO instance
variables and create the DS and assign the “dataobject”
in your NVO constructor.
• But check application server memory usage!
PB ErrorLogging Class
 Writes to plugin log file.
• %PB_SERVER_HOME%\logs\pb-server.log
 PowerScript Usage:
ErrorLogging logger
getContextService(“ErrorLogging”, logger)
logger.log(“My Message”)
PB TransactionServer Class
 Supported methods:
• CreateInstance, DisableCommit, EnableCommit, IsCallerInRole,
IsTransactionAborted, SetAbort, SetComplete.
 CreateInstance notes (for NVO to NVO inter-component calls):
• Use the two argument form and specify full JNDI name of target
component, e.g. (error checking code omitted for brevity)
TransactionServer ts
getContextService(“TransactionServer”, ts)
pbtest_MyComp comp // remember to generate and use proxies
ts.createInstance(comp, “pbtest/MyComp”)
// call methods on comp
• If the target NVO is not in the same EJB-JAR as the calling NVO, you
might encounter issues with your application server’s class loader (e.g.
ClassCastException). Sybase will NOT support NVO inter-component
calls across EJB-JAR boundaries if you encounter class loader issues.
Consult your application server vendor for assistance with class loader
issues across EJB-JAR boundaries.
Development – EJB Clients
 For EJB clients, use your application server’s facilities for EJB
client access.
 If your package is named “MyPackage”, and your component is
named “MyComp”:
• The generated EJB home interface is named
MyPackage.ejb.MyCompHome
• The generated EJB remote interface is named
MyPackage.ejb.MyComp
• The Java package for home and remote interfaces can be
overridden. See “Deployment – Java Packages”.
• The JNDI name is “MyPackage/MyComp”.
 For co-located clients (e.g. JSP, servlet, other EJBs) you can use
ejb-refs or direct JNDI lookups.
Development – PB Clients
 PowerBuilder has built-in facilities for calling EJBs in
third party application servers: EJB proxy Project
 Check the PowerBuilder documentation for the
EJBConnection class and your application server
documentation for general instructions.
 Alternatively, we provide a proxy server to permit native
IIOP communication (without client-side JVM) from PB
clients to NVOs running in your EJB server. See next
page…
PB Clients – Proxy Server
 Check the PowerBuilder documentation for usage of the
Connection.CreateInstance method.
 The Proxy Server runs alongside your application server on
your application server machine. It starts automatically when
your application server starts the plugin.
 You can define multiple proxy servers if you have multiple
application servers. Your client can use multiple connection
URLs for load balancing and failover, e.g.
• iiop://myhost1:2000;iiop://myhost:2000
 To configure your proxy server(s), edit:
• config\ejb-proxy-XXX.xml
 We will provide a redistributable “Client Edition” of the proxy
server, in case you don’t want to run it on the server host.
Proxies for “pure” EJBs
 You can also generate proxies to allow PB clients and
PB components to call “pure” EJBs.
 Use the “deploy” command:
• bin\deploy –proxy myejb.jar
 Then use the “Application Server Proxy” features of the
PB IDE to generate PowerBuilder proxies.
 Use Connection.CreateInstance to call from PB clients.
 Use TransactionServer.CreateInstance to call from PB
components.
 There are some restrictions on data types that can be
mapped, check the documentation for full details.
Web DataWindow
 Supports browser-based clients using XML,
XHTML, HTML. See DataWindow Programmer's
Guide for general information.
• http://sybooks.sybase.com/onlinebooks/grouppb/pbg1000e/dwprgug
 Check PB Server Plugin documentation for latest
details on using the Web DataWindow.
 This is not considered a “P1” feature for the initial
release of the PB server plugin. If we run into
problems, we may defer full support of this feature
to a subsequent release.(This is the case in version
1.0, it might work but is not guarantied)
Deployment – General
 In the PB Project Painter, for your component project(s),
specify connection information as follows:
•
•
•
•
Host name: TCP host name for server machine
Port - 9000
Login ID - admin@system
Login password - (remember, you set it!)
 You can override the host name and port number that
the server uses for its deployment listener by changing
the deploy.host and deploy.port properties in
config/pb-server-XXX.xml.
 Remember to re-run ‘configure’.
Demo
Step 1: lets do a simple NVO deployement using the Application
Server Component Target
Step 2: lets test the deployed component with the pb-server-test.bat
(NB. We can get here a nice gage of the expected performance, compare
with EAServer 6!!!)
Step 3: create a connection cache for the test database.
(customise sybase-ds.xml and save it into
%jboss_home%\server\default\deploy)
Step 4: add some more functions to the NVO to test different
aspects ( time management, db connectivity…)
Step 5: let’s look at a couple of sample applications and see what
can go wrong!!!
Deployment – Test & Debug
 “Live Editing” is useful for quickly testing changes
without a full redeploy.
• Check the PowerBuilder “Application Techniques” document
for details.
• Set the ejbDeployIfUnchanged property to false when using
live editing. This is in:
– %PB_SERVER_HOME%\config\pb-server-XXX.xml
And remember to re-run ‘configure’!
 “Remote Debugging” is very useful too!
Remote Debugging
 Use the “Start Remote” button in the PowerBuilder
debugger to start a remote debugging session, as if
debugging a component in Sybase EAServer.
 Check the PowerBuilder documentation for detailed
instructions.
Deployment – Web Services
 Not enabled by default.
 Enable via check-box in Project Painter Properties.
 Your application server must support J2EE 1.4.
 The ResultSet return type is not supported for web
services. Use array and structure types instead.
Deployment – Java Packages
 Defaults to “xyz.ejb” for NVO package “xyz”.
 In the Project Painter Properties, you can specify an
alternate Java package.
 Recommendation: use Java package naming
conventions, e.g. “com.example.bank”.
 This is required for NVO to be exposed as Webservice.
Deployment – Generated Code
 Base directory for generated files:
• %PB_SERVER_HOME%\genfiles\java
 Subdirectories for:
•
•
•
•
applications
classes
ejbjars
src
 You can generally delete generated code after deployment, but this
will slow down subsequent redeployments. If using the “Proxy
Server”, don’t delete the generated files. The Proxy Server uses
some of them at run time.
Deployment – Naming Conventions
 Enable “camel case” option to map PB identifiers to Java style
identifiers.
• bin\configure camel-case-on
• bin\configure camel-case-off
(if you don’t like it)
 PowerScript identifiers with underscore are mapped to Java
“camel case” for parameter names and NVO methods, e.g.
“my_simple_method” maps to “mySimpleMethod”.
 A leading capital is used for structure types e.g. “my_structure”
maps to “MyStructure”. Structure field names are not changed.
 Component names are not changed from what you specify in the
Project Painter. We recommend using the Java class naming
conventions (e.g. “MyComp”).
 Your NVO implementation class can use any name.
 Note: You must enable the camel case option if you will be
exposing components as web services.
Deployment – Repository Files
 Base directory for repository files:
• %PB_SERVER_HOME%\Repository
 Subdirectories for:
•
•
•
•
IDL (interface definitions)
Component (component properties and PBDs)
Instance (server and data source properties)
Package (package properties)
 These are needed during deployment and at runtime.
Deployment – Security Roles
 Default to “unchecked”.
 In the Project Painter Properties dialog, you can specify
required roles (logical role names) for each component.
 Use your application server’s facilities (if necessary) for
mapping these logical role names onto physical roles.
Deployment – Cluster Notes
 If your application server is running in a cluster, and
each server has its own copy of the PB plugin directory,
you must either:
• Deploy all components to all servers, or
• Copy the contents of the “config”, “deploy”, “genfiles” and
“Repository” directories to all target servers, and use your
application server’s facilities for distributing the deployed
EJB-JAR files across the cluster.
Deployment – Validation Test
 Using the PowerBuilder IDE, define a component with package name
“pbtest” and component name “MyComp”.
 Add some business methods of your choice. If you are feeling brave, you
might want to try some methods with database access 
 Deploy to your application server.
 Run the following commands:
• cd %PB_SERVER_HOME%
• bin\pb-server-test
 The test program will try to call all methods of your component with “fake”
parameter values (e.g. 1, 2, “S1”, S2”, …)
 If you have a method named “perftest”, the test program will call it
repeatedly to provide basic performance metrics.
 Source code for the test client program can be found in
src/java/com/sybase/pb/server/PbServerTest.java.
Troubleshooting
 PB application server plugin log:
• %PB_SERVER_HOME%\logs\pb-server.log
 PB application server proxy log:
• %PB_SERVER_HOME%\logs\ejb-proxy.log
 Your application server log file(s).
 Your application server console window (if applicable).
Licensing, Pricing, Release…
• Licensing: runtime deployment fee
• Pricing: < $500 per CPU
• Release date: Q4 2006
Questions?
Configuration - WebLogic
 Run the following commands (Windows)
• cd %PB_SERVER_HOME%
• bin\set-admin-password
• bin\configure pb-server-weblogic
–Dwls.home=wls-home-dir
(e.g. “–Dwls.home=c:\bea\weblogic90”)
 To customize the configuration XML scripts edit:
• config\ejb-proxy-weblogic.xml
• config\pb-server-weblogic.xml
 If you edit an XML script, re-run the above ‘configure’
command. Hint: check if the scripts require editing
before running ‘configure’ for the first time.
Configuration - WebSphere
 Run the following commands (Windows)
• cd %PB_SERVER_HOME%
• bin\set-admin-password
• bin\configure pb-server-websphere
–Dwas.home=was-home-dir
(e.g. “–Dwas.home=c:\Program Files\IBM\WebSphere\AppServer”)
 To customize the configuration XML scripts edit:
• config\ejb-proxy-websphere.xml
• config\pb-server-websphere.xml
 If you edit an XML script, re-run the above ‘configure’ command.
Hint: check if the scripts require editing before running ‘configure’
for the first time.
Once Only Tasks – WebLogic
 Start the server.
 Using the WebLogic console, define a Startup Class
using class name com.sybase.pb.server.PbServerStart.
 Shutdown the server.
Once Only Tasks - WebSphere
 Start the server.
 Using the WebSphere admin console, Enable the
“Startup beans service”, and then deploy the PB startup
service:
• %PB_SERVER_HOME%\deploy\websphere\pbstartup.jar
 Shutdown the server.
Deployment – WebLogic Notes
 Ensure that your server is running in “development”
mode.
 To configure the deployment directory, set the
“deploy.dir” property in:
• %PB_SERVER_HOME%\config\pb-server-weblogic.xml
 Also check the “wls.domain” property is correct for your
server.
(you’ll realise it very quickly).
Deployment - WebSphere
 To customize the WebSphere Ant deployment options, edit
(under %PB_SERVER_HOME%):
• config/ws-ejb-deploy.xml
• config/ws-install-app.xml
 Consult your WebSphere documentation for further details.
 WebSphere EJB-JAR deployment can be a bit slow
 If you get impatient, you might consider using a free server
such as JBoss or EAServer Developer Edition 6.0 for initial
development, and deploying to WebSphere once your
application is tested.