IA366 DDS Enterprise Application Framework

1
IA366DDS Enterprise Application Framework
Alex Whitney Managing Principal Dynamic Data
Solutions awhitney_at_dyn-data.com
2
Agenda

• Why Enterprise Application Framework (EAF)
• Major Features
• Major Components and Services
• Demonstration

3
Why Did We Develop the EAF

• EAF was developed to help our customers guarantee
  the success of their EAServer development efforts
• We felt that development community as a whole
  could benefit from this kind of functionality

4
Why Did We Develop EAF

• We decided that the best solution would be to
  provide the DDS EAF as an open source offering to
  the PowerBuilder community
• EAF is to EAS as PFC is to PowerBuilder
• It gives developers a leg up on the development
  process
• Utilize their time on solving business problems,
  not technical ones

5
Major Features

• ResultSet Vs. Blob
• No DataWindow syntax required on client
• Logical Unit of Work
• Single point of entry for all clients
• Interface Manager Business Object
• HTMLDW Support
• Multilingual support
• Tracing and debugging support

6
Resultset Vs. Blob

• ResultSets are Corba compliant and usable from
  many clients
• Blobs require a PB Datastore or DataWindow at the
  client

7
No Datawindow Syntax Required on Client

• Updates to client applications can be much
  simpler
• Syntax is sent to client as requested
• Options
• Only Syntax
• Only Data
• Syntax and Data
• Syntax As Needed

8
Logical Unit of Work

• Implicit in how data is transmitted between
  client application and component
• Data for multiple DataWindows are sent as a group
• Both retrieves and updates can be grouped
• One round trip between client and server for an
  update or retrieve

9
Logical Unit of Work
10
Single Point of Entry for All Clients

• All data access is treated the same no matter
  what the client is
• InterfaceManager Component delegates all requests
  as required
• DataSet Object
• BO Component

11
Single Point of Entry for All Clients
12
Business Object

• Allows a single point of validation for updates
  from multiple IMs
• Supports DataWindow validations as well as custom
  logic

13
Business Object
14
HTMLDW Support

• Permits the developer to treat web clients just
  like a PB client
• Same retrieval and update logic regardless of
  client

15
HTMLDW Support
16
Multilingual Support

• Display DataWindows and messages in a specific
  language that is tied to a session

17
Multilingual Support
18
Tracing and Debugging Support

• Extensive support for writing information to the
  Jaguar log file
• Can be controlled from the components Jaguar
  properties
• com.sybase.jaguar.component.ddseafdebugtrue
• com.sybase.jaguar.component.ddseafdetailedtrue
• com.sybase.jaguar.component.ddseaftracetrue

19
Tracing and Debugging Support
20
Major Components and Services

• DDSEAF_n_cst_component
• Interface structure
• InterfaceManager Component
• BOManager Component
• DataSet Object
• InterfaceService Object
• SessionManager Component
• MessageManager Component
• DDSEAF_n_cst_resultsetservice

21
DDSEAF_n_cst_component

• Base class for all PB components
• Database access
• Methods for configuring a connection to the
  database
• Methods for connecting and disconnecting
• No default connection or disconnection logic at
  this level

22
DDSEAF_n_cst_component

• Transaction management
• SetComplete/SetAbort() wrappers
• IsInTransaction()
• IsTransactionAborted()
• Logging
• Reference to logging service object
• Debugging
• Automatic setting of debug variables from
  component properties

23
DDSEAF_n_cst_component

• Error handling
• Get/SetLastError() functions
• Communication with other components via
  ObjectService reference variable
• SessionManager
• MessageManager

24
Interface Structure

• Communication between server and client is
  handled via the Interface Structure
• Structure allows multiple DataSets to be
  transferred between the client and
  InterfaceManager as a single LUW

25
InterfaceManager Component

• Manages requests for data from client
  applications
• Requests are for a single (or multiple) set of
  data (DataSet)
• Each DataSets ResultSet is defined by
• A DataWindow object
• A more sophisticated DataSet object

26
InterfaceManager Component

• Can manage one to many DataSets
• Each DataSet has zero to many associated
  BusinessObjects assigned to it
• Updates are
• Delegated to a BO
• Performed via a DataSet Object
• Not allowed
• Defined by DataSet configuration

27
InterfaceManager Component

• LUW scoped to an InterfaceManager
• LUW may not span multiple IMs
• The same DataSet can reside on multiple IMs
• BOs may be called from multiple IMs
• Can work with all DataSets in a LUW

28
InterfaceManager Component

• Example Constructor Code
• // Set up the Transaction
• ls_bo DDSEAF_Examples/BOCustomer
• SQLCA.initialize('odbc', "UseContextObject
  'Yes',cachename'EASDemo'")
• registerDataset('custpicklist',
  d_customerpicklist)
• registerDataset('customer', "d_customer", ,
  ls_bo)

29
InterfaceManager Component

• // Registers a DataSet object - Much more
  flexible than a single DataWindow object
• lnv_customer create ds_customer
• registerDataset('customer', lnv_customer, ls_bo,
  ls_bo)

30
BOManager Component

• Normally configured to manage all updates for a
  specific table
• Supports DataWindow validation rules
• Can apply data rules to the syntax of the
  DataWindow object prior to a retrieve
• Supports the addition of custom logic

31
BOManager Component

• Extract only the columns that belong to them for
  updating
• Multi-table updates, where rows have a 1-to-1
  relationship, are automatic if all BOs that
  manage the tables are registered with the DataSet
  at the IM

32
BOManager Component

• Example Constructor Code
• // Set up the Transaction
• SQLCA.initialize('odbc', "UseContextObject
  'Yes',cachename'EASDemo'")
• // Set the dataobject
• setDataobject("d_bocustomer")

33
DataSet Object

• Allows for extensions to retrieval logic
• If a BO is not used then the DataSet object can
  be used to extend update logic
• Allows for customization of generated HTML

34
DataSet Object

• Example Constructor Code
• setDataobject('d_customer', 1)
• setDataobject('d_customer_spanish', 2)

35
InterfaceService Object

• Client side service object that manages
  interactions between the client and an
  InterfaceManager component
• One InterfaceService per LUW
• LUW normally scoped at window level
• DataSets are configured to use either a
  DataWindow control or a DataStore as the target

36
InterfaceService Object

• DataSets can be grouped
• DataSets can belong to more than one group
• Retrieves and updates can be done for
• A single DataSet or group
• A series of DataSets or groups
• All registered DataSets

37
InterfaceService Object

• Update process performs accepttext() and checks
  for required fields before starting the update
• Only DataSets that have changes are sent to the
  server
• Only rows that have been updated, inserted or
  deleted are sent to the server

38
InterfaceService Object

• Example Open Event Code
• ll_rc inv_interface.setConnection(icn_jaguar)
• If ll_rc ltgt 1 Then
• MessageBox (this.ClassName(), "Call
  inv_interface.setConnection() failed!"
• inv_interface.getLastError() "rnRC"
  String(ll_rc))
• Return
• End If

39
InterfaceService Object

• ll_rc inv_interface.setInterfaceManager('IMCust'
  )
• // Register the DataSet(s)
• ll_rc inv_interface.registerDataset("customer",
  "customer", "windowgroup", dw_customer,
  inv_interface.RETRIEVE_FULLONNEED)

40
InterfaceService Object

• Example Update code
• ll_rc inv_interface.update ("customer")
• If ll_rc lt 0 Then
• MessageBox (this.ClassName(),
• "Call inv_interface.update() failed!rnrn"
  inv_interface.getLastError() "rnRC"
  String(ll_rc))
• Return
• End If

41
InterfaceService Object

• // Cast to key value to the appropriate type and
  add the Retrieval Argument
• ll_key long(ls_key)
• ll_rc inv_interface.resetArguments( "customer")
• ll_rc inv_interface.addArgument ("customer",
  ll_key)
• // Perform the request for retrieval
• ll_rc inv_interface.retrieve ("windowgroup")

42
SessionManager Component

• Provides a way to store session specific
  information at the server
• Written in Java for multithreaded support

43
MessageManager Component

• Provides standardized message handling for both
  server and client
• Written in Java for multithreaded support

44
DDSEAF_n_cst_resultsetservice

• Provides conversion from DataWindow/Datastore to
  ResultSet style structure and back
• Extracts all buffers from a DataStore/DataWindow
  and converts them to resultsets

45
DDSEAF_n_cst_resultsetservice

• Does so by isolating each buffer(6 of them)
• DELETED
• NEW
• MODIFIED_NEW
• UNMODIFIED_ORIGINAL
• MODIFIED_ORIGINAL
• MODIFIED_CURRENT
• Finds all DDDW columns and converts their
  contents to a ResultSet

46
DDSEAF_n_cst_resultsetservice

• Reverses the process on the receiving end
• Ensures that all status flags are properly set
  after being converted back to a DataStore
  /DataWindow

47
InterfaceManager Component

• Public methods
• retrieve ( ref s_interface astr_interface )
  returns long
• All DataSets in the retrieval list are retrieved
• update ( ref s_interface astr_interface )
  returns long
• All DataSets in the update list are updated
• generate ( ref s_htmldwprops htmldwprops )
  returns string
• Request for HTML DataWindow interface

48
InterfaceManager Component

• Public methods
• getregistered ( ref string as_datasetids )
  returns long
• Returns a list of all registered DataSets
• getargumentdefinition ( string as_datasetid, ref
  string as_argnames, ref string
  as_argdatatypes ) returns long
• Returns the argument list and their datatypes for
  a DataSet

49
InterfaceManager Component

• Configuration concepts and commonly used methods
• Configure database connection
• SQLCA.initialize('odbc', "UseContextObject
  'Yes',cachename'EASDemo'")
• Configure DataSets
• If a DataSet object is NOT specified then a
  default one will be created and used for the
  DataSet

50
InterfaceManager Component

• Configure DataSets (continued)
• Use customized DataSet object to alter default
  behavior
• Retrieve only
• DataSet is updated by the IM
• Set data rules with a BO, Update via IM
• Retrieve/update w/BO for update and BO for
  setting data rules. Data rules BO is optional

51
InterfaceManager Component

• Configure DataSets (continued)
• Combinations of multiple BOs for Data Rules and
  updating
• 0 to many retrieve BOs
• 0 to many update BOs

52
InterfaceManager Component

• Configurable objects
• Allow the developer to specify a different
  default DataSet object
• setdataset ( string as_dataset ) returns long
• Allow the developer to specify a different
  default DataStore object
• setdatastore ( string as_datastore ) returns
  long

53
InterfaceManager Component

• Protected Methods
• getdatasetidx ( string as_datasetid ) returns
  long
• Returns offset into inv_registerattrib array
  which contains information about each registered
  DataSet
• Returns 0 if DataSet NOT registered

54
InterfaceManager Component

• Basic Usage
• Constructor
• Configure database connection (but do not
  connect)
• Register DataSets
• Activate
• Reset any additional instance variables that you
  may added, IF they need to be reset between
  invocations

55
InterfaceManager Component

• Basic Usage (continued)
• Deactivate
• Always release any connections that may have been
  acquired
• SQLCA automatically released by framework
• Destructor
• Release any other resources that may have been
  acquired

56
InterfaceManager Component

• Basic Usage (continued)
• Methods
• Only connect to Database if needed
• Update/Retrieve
• Stub methods are provided to work with the entire
  LUW

57
BOManager Component

• Public methods
• update ( ref s_update astr_update ) returns long
• Calls other functions to perform work
• Order of execution
• updatestart()
• updatevalidate()
• updateprepare()
• updatemain()
• updateend()

58
BOManager Component

• Configuration concepts and methods
• Configure database connection
• SQLCA.initialize('odbc', "UseContextObject
  'Yes',cachename'EASDemo'")
• Specify the DataWindow object to be used for
  updating
• setdataobject ( string as_dataobject ) returns
  long

59
BOManager Component

• Configurable objects
• Override the default DataAccess object
• Specify a different default DataStore object

60
BOManager Component

• Basic Usage
• Constructor
• Configure database connection (but do not
  connect)
• Register dataobject
• Deactivate
• Release database connection

61
BOManager Component

• Basic Usage (continued)
• Methods
• assignrequiredfields ( ref n_datastore
  ads_working, s_columninfo astr_columninfo )
  returns long
• Add required fields to the DataWindow object at
  runtime
• Called by the UpdateValidate function as part of
  the update process

62
BOManager Component

• Basic Usage (continued)
• updatestart ( n_datastore ads_working,
  s_columninfo astr_columninfo, s_extradata
  astr_extradata, ref string as_result ) returns
  long
• Do any initial checking
• Can be used to override the entire update process

63
BOManager Component

• Basic Usage (continued)
• updatevalidate ( n_datastore ads_working,
  s_columninfo astr_columninfo, s_extradata
  astr_extradata, ref string as_result ) returns
  long
• Add validation logic
• updateprepare ( n_datastore ads_working,
  s_columninfo astr_columninfo, s_extradata
  astr_extradata, ref string as_result ) returns
  long
• Perform additional data preparation steps prior
  to the actual update

64
BOManager Component

• Basic Usage (continued)
• updatemain ( n_datastore ads_working,
  s_columninfo astr_columninfo, s_extradata
  astr_extradata, ref string as_result ) returns
  long
• Update is performed here
• updateend ( n_datastore ads_working, s_columninfo
  astr_columninfo, s_extradata astr_extradata,
  ref string as_result ) returns long
• Perform any post update processing

65
DataSet Object

• Public methods
• Specify the message style of HTML errors
• setmessagestyle ( long al_style ) returns long
• al_style ADDONLOADMESSAGE will cause an alert
  message to appear
• al_style ADDMESSAGE will embed the message in
  the HTML by modifying the DataWindow syntax

66
DataSet Object

• Public methods (continued)
• htmlfinalcustom ( ref s_htmldwprops
  astr_htmldwprops, ref n_datastore ads_working,
  ref any aa_args, ref s_extradata
  astr_extradata, ref string as_html ) returns
  long
• Make changes to the HTML after it has been
  generated

67
DataSet Object

• Public methods (continued)
• htmlinitialcustom ( ref s_htmldwprops
  astr_htmldwprops, ref n_datastore ads_working,
  ref any aa_args, ref s_extradata
  astr_extradata, ref string as_html ) returns
  long
• Make changes to the data or other information
  before the HTML is generated
• Can be used to generate custom HTML instead of
  the default HTML

68
DataSet Object

• Configuration concepts and methods
• Specify the DataWindow object to be used
• setdataobject ( string as_dataobject, long
  al_languageid ) returns long
• Configurable objects
• Override the default DataAccess object
• Allows developer to specify a different default
  DataStore object

69
DataSet Object

• Basic Usage
• Constructor
• Register dataobject
• Methods
• Retrieve ( ref n_datastore ads_working, ref any
  aa_args, ref s_extradata astr_extradata )
  returns long
• Calls the Retrievestart, Retrievemain and
  Retrieveend functions

70
DataSet Object

• Basic Usage (continued)
• Retrievestart ( ref n_datastore ads_working, ref
  any aa_args, ref s_extradata astr_extradata )
  returns long
• Can be used to manage DDDWs that have retrieval
  arguments
• Retrievemain ( ref n_datastore ads_working, ref
  any aa_args, ref s_extradata astr_extradata )
  returns long

71
DataSet Object

• Basic Usage (continued)
• Retrieveend ( ref n_datastore ads_working, ref
  any aa_args, ref s_extradata astr_extradata )
  returns long
• Can be used to do additional filtering of rows or
  other validation before sending data to the
  client
• GetRetrieveAction ( ) returns string
• Determine the action type of the retrieve
• Data
• Syntax
• Data and Syntax

72
DataSet Object

• Basic Usage (continued)
• Updatestart ( n_datastore ads_working,
  s_extradata astr_extradata, ref string as_result
  ) returns long
• Perform pre-update data manipulation
• Returns
• 2 - Success - Update has been performed (skip
  update process)
• 1 - Success - Continue Action
• 0 - Do not perform the update
• -1 - Failure - Do not perform the update

73
DataSet Object

• Basic Usage (continued)
• UpdateValidate
• Add validation logic
• UpdatePrepare
• Perform any data preparation prior to update
• UpdateMain ( n_datastore ads_working, s_extradata
  astr_extradata, ref string as_result ) returns
  long
• Update is performed here
• UpdateEnd
• Do any clean up here

74
Interface Service Object

• Public methods
• Accepttext, just like the one on a DataWindow
• accepttext ( ) returns long
• accepttext ( string as_dataset ) returns long
• accepttext ( string as_datasets ) returns long
  
• Add arguments for a DataSet
• addargument ( string as_datasetid, any aa_arg )
  returns long
• addargument ( string as_datasetid, any aa_arg,
  boolean ab_array ) returns long

75
Interface Service Object

• Public methods (continued)
• Change the action type after the initial
  registration
• changeregisteredactiontype ( string as_datasetid,
  string as_actiontype ) returns long
• Error handling
• getlasterror ( ) returns string
• What DataSets are registered
• getregistered ( ref string as_datasetids )
  returns long

76
Interface Service Object

• Public methods (continued)
• Register a DataSet
• Allow any combination of
• DataWindow or Datastore as target
• Any number of group names
• Clear out any existing arguments for DataSet(s)
• resetarguments ( ) returns long
• resetarguments ( string as_dataset ) returns
  long
• resetarguments ( string as_datasets ) returns
  long

77
Interface Service Object

• Public methods (continued)
• Clear out all registered DataSets
• resetregistered ( ) returns long
• Retrieve some combination of DataSets
• retrieve ( ) returns long
• retrieve ( string as_dataset ) returns long
• retrieve ( string as_datasets ) returns long
• Tell the object what connection object to use
• setconnection ( n_connection acn_obj ) returns
  long

78
Interface Service Object

• Public methods (continued)
• What IM is it to use
• setinterfacemanager ( string as_name ) returns
  long
• Update some combination of DataSets
• update ( ) returns long
• update ( string as_dataset ) returns long
• update ( string as_datasets ) returns long

79
Interface Service Object

• Public methods (continued)
• Any updates pending?
• updatespending ( ) returns long
• updatespending ( string as_dataset ) returns
  long
• updatespending ( string as_datasets ) returns
  long

80
SessionManager Component

• Provides the ability to store session specific
  information at the server
• Public functions
• deleteproperty ( string as_property ) returns
  long
• deletesession ( ) returns long
• getproperty ( string property, ref string value)
  returns long
• getsessionid ( ref string as_id ) returns long
• setproperty ( string as_property, string as_value
  ) returns long

81
MessageManager Component

• Provide a means of storing messages at the server
• getmessage ( string as_messageid, ref string
  as_message ) returns long
• Multilingual option
• Maps message request to the appropriate language
  if implemented

82
HTML Client Interface

• Provide a means to access the components from
  PowerDynamo just like you can from PB
• Implemented as a PowerDynamo class (equivalent to
  a NVO)

83
HTML Client Interface

• Public Methods
• String generate( actionResult
• Gathers all needed information and calls the
  component
• setButtons( buttons )
• Expects a string of button names separated by
  commas
• setUserID( userID )
• Set User ID for Jaguar CTS Connection

84
HTML Client Interface

• Public Methods (continued)
• setPassword( password )
• Set Password for Jaguar CTS Connection
• setInterfaceClass( interfaceClass )
• Set Interface Class Name
• setInterfaceManagerName( interfaceManagerName )
• Set Name of Interface Manager CORBA Object
• setName( name )
• Set Name for HTML DW

85
HTML Client Interface

• Public Methods (continued)
• setDataSet( name )
• //Set DataSet for HTML DW
• setForm( form )
• Set FORM Nature of Page
• setScript( script )
• Set Script Capability Nature of Page
• setValidation( validation )
• Set Validation Capability Nature of Page

86
HTML Client Interface

• Public Methods (continued)
• setEvents( events )
• Set Events Capability Nature of Page
• setFormatting( formatting )
• Set Formatting Capability Nature of Page
• setPageSize( pagesize )
• Set Page Size Capability Nature of Page
• addArg( type, value )
• Add Retrieval Argument

87
HTML Client Interface

• Public Methods (continued)
• addArgArray( type, value )
• Support array's as retrieval arguments
• addColumnLink( columnName, linkURL, linkArgs,
  linkTarget )
• Add Column Link
• setHostURL( hostURL )
• Set Host Name for Jaguar CTS Server

88
HTML Client Interface

• Configuration concepts
• lt!--SCRIPT
• // Perform the Import of the DDSEAF code
• import (site.GetRootDocument().location
  "/ddseaf_htmldw.ssc")
• // Create an instance of the DDSEAF HTML
  DataWindow passing
• // it the Package/Component name
• var htmldw new ddseaf_htmldw(
  "EAF_Class/imcustomer")

89
HTML Client Interface

• Configuration concepts (continued)
• // Configure the instance of the DDSEAF HTML
  DataWindow for
• // the desired behavior
• htmldw.setForm( true )
• htmldw.setName( "htmldw" )
• htmldw.setScript( false )
• htmldw.setFormatting( false )
• htmldw.setValidation( false )
• htmldw.setEvents( true )

90
HTML Client Interface

• Configuration concepts (continued)
• htmldw.setDataset( "customerpicklist" )
• htmldw.setPageSize(20) // display only 20 rows
  at a time
• htmldw.setButtons( "Next,Prior" )
• htmldw.addColumnLink( "id", "custdetail.html",
  "linkid'string(id)'", "right" )
• // Request the generation of the instance
• document.WriteLn( htmldw.generate() )
• --gt

91
HTML Client Interface

• Configuration concepts (continued)
• Configuration for updateable DataWindow with
  arguments
• htmldw.setForm( true )
• htmldw.setName( "htmldw" )
• htmldw.setScript( true )
• htmldw.setFormatting( true )
• htmldw.setValidation( true )
• htmldw.setEvents( true )

92
HTML Client Interface

• Configuration concepts (continued)
• htmldw.setDataset( "customer" )
• htmldw.addArg( "number",document.value.linkid )
• htmldw.setPageSize(0) // display all rows
• htmldw.setButtons( "Gap015,Retrieve,Gap015,Update"
  )

93
HTML Server Interface

• InterfaceManager.generate ( ref s_htmldwprops
  htmldwprops ) returns string
• Generate method determines the action
• Executes a HTMLAccept()
• Repopulate DataSet and apply context and action
• Retrieves performed via DataSet retrieve process
• Updates are not performed
• If the action is update then the update is
  delegated to the IM.update() method

94
HTML Server Interface

• Errors are returned to PowerDynamo in the HTML
  text and ActionResult parameter

95
Demonstration
96
Thank You

• Alex Whitney
• awhitney_at_dyn-data.com
• Dynamic Data Solutions, Inc
• http//www.dyn-data.com
• 888.823.DATA