More Related Content
Similar to SHOW107: The DataSource Session: Take XPages data boldly where no XPages data has been taken before (20)
More from Stephan H. Wissel (9)
SHOW107: The DataSource Session: Take XPages data boldly where no XPages data has been taken before
- 1. SHOW107 The Data Source
Session: Take XPages data
boldly where no XPages data
has been taken before
Jim Quill | XPages Developer | IBM Ireland
Stephan H. Wissel | LTPA | IBM Singapore
© 2011 IBM Corporation
- 2. Agenda
●Overview – options to connect to data
●The Data Source object model
●Setting up your development environment
●Simple CSV file Data Source
●Debugging your code
●Connecting to RDBMS
●Connecting to Non relational data sources
●Deploying your data source
●Q &A
© 2011 IBM Corporation 2
- 3. Overview – options to connect to data
● Built-in DataSources
─ Domino® View
─ Domino® Document
─
● SeverSide JavaScript
─ Write custom Java™ code to connect any data source and return that data
as an object, array, List, ResultSet, or DataModel will enable XPages
controls to consume that data.
─
● Any control that holds data, for display or editing can be bound to an item of
data, a field in a Domino document or a property of a Managed Bean, for
example.
●
● Container controls, i.e. DataTable, Repeat, and View Panel can be bound to a
single item or a collection of items and will iterate over the data
–
© 2011 IBM Corporation
- 4. Overview – options to connect to data
● Demo 1
─ Create an array
─ Put it into view
scope
─ Reference data
using EL
expression
─
●
© 2011 IBM Corporation
- 5. Overview – options to connect to data
● Built-in DataSources Benefits
─
─ declaratively add and reuse custom data sources to an XPage,
─
─ computed properties
─
─ easy access the data souce in SSJS
─
─ nest DataSources so contents of one data source can be bound to
computed properties of another data source defined on an inner panel that
is in a Repeat control
─
─ control behavoiur via URL parameters
─
─ add your own query/postSaveEvents, and more
© 2011 IBM Corporation
- 6. Overview – options to connect to data
● Objectives for todays session
─
─ Write a data source that
reads a CSV file from the
local filesystem
─
─
─
─
─ Write a data source that
reads data from an RDBMS
by executing SQL via JDBC
–
●
●
─
© 2011 IBM Corporation
- 7. Agenda
●Overview – options to connect to data
●The Data Source object model
●Setting up your development environment
●The first data source
●Debugging your code
●Connecting to RDBMS
●Connecting to Non relational data sources
●Deploying your data source
●Q &A
© 2011 IBM Corporation 7
- 8. The Data Source Object Model
● For the two core storage artifacts, View and Documents, XPages provides a
convenient mechanism to declaratively add these two data sources to your
application without any coding
─ All properties can be computed using JavaScript or an EL expression
─ Tight integration with a set of easy to use Simple Actions for working with
Documents and View
─ Ability to specify request parameters to control and influence the behavior
of the data source
●
● Within the XPages framework, data sources are based on two key classes
─ com.ibm.xsp.model.AbstractDataSource
─ com.ibm.xsp.model.AbstractDataContainer
─
–
© 2011 IBM Corporation
- 9. The Data Source Object Model
●
─
ComponentBindingObject ValueBindingObject
–
DataPublishingObject Externalizable
StateHolder DataContainer
DataSource
AbstractDataSource AbstractDataContainer
© 2011 IBM Corporation
- 10. The Data Source Object Model
● AbstractDataSource Responsibilities
─ Data source id management
– BeanId
– UniqueId
─ RuntimeProperty management
– Computed properties can be saved as runtime property so its values
doesn't have to be repeatedly calculated
─ State Management
– Base properties var, scope, ignoreRequestParams,
requestParamPrefix
– Property accessors for state of component to be recreated
─ Data Container Management
─ DataPublishing
– pushData, popData – publishes the DataModel to request scope using
the specified var attribute as the key
●
© 2011 IBM Corporation
- 11. The Data Source Object Model
● Data Container Responsibilities
─ Externalizable support
─ Manages the life cycle of the data – if it doesn't continuously store the data
between requests, it knows how to retrieve it.
─
─
●
© 2011 IBM Corporation
- 12. Agenda
●Overview – options to connect to data
●The Data Source object model
●Setting up your development environment
●The first data source
●Debugging your code
●Connecting to RDBMS
●Connecting to Non relational data sources
●Deploying your data source
●Q &A
© 2011 IBM Corporation 12
- 13. Setting up your development environment
● What you need
─ IBM® Lotus Domino® Designer 8.5.2
─ IBM® Lotus Domino® 8.5.2
─ IBM® DB2®
─
─
● What you should have to hand:
─ Javadoc
– XPages Extensibility API Documentation
– http://www-10.lotus.com/ldd/ddwiki.nsf/dx/XPages_Extensibility_API_Document
ation
─
─ Wiki
– XPages Extensibility API Developers Guide
– http://www-10.lotus.com/ldd/ddwiki.nsf/dx/Master_Table_of_Contents_for_XPag
es_Extensibility_APIs_Developer_Guide
● © 2011 IBM Corporation
- 14. Agenda
●Overview – options to connect to data
●The Data Source object model
●Setting up your development environment
●Simple CSV File Data Source
●Debugging your code
●Connecting to RDBMS
●Connecting to Non relational data sources
●Deploying your data source
●Q &A
© 2011 IBM Corporation 14
- 15. Simple CSV Data Source
● Create a New Application
─ Menu > File > New
●
© 2011 IBM Corporation
- 16. Simple CSV Data Source
● Overview
─ Create a New Application
─ Project setup
─ Extend AbstractDataSource
– Manages the DataSource properties
─ Extend AbstractDataContainer
– Manages the Data life cycle, caching, refreshing
─ Create an xsp-config file that describes the DataSource so it can integrate
with Lotus Domino® Designer and the Xpages Framework
●
●
© 2011 IBM Corporation
- 17. Simple CSV Data Source
● Application Setup
─ Grant Anonymous Manager access level File > Application > Access Control...
─ Specify oneuiv2 as the Web theme. File > Application > Properties > Xpages
─ CTRL-S to save changes
© 2011 IBM Corporation
- 18. Simple CSV Data Source
● Switch to the Java™ perspective
─ Window > Open Perspective > Java
●
● Shortcut
─ CTRL-F8
●
●
● A virtual file system for the NSF
─ organized like a WAR
© 2011 IBM Corporation
- 19. Simple CSV Data Source
● Create a new Source Folder
─ Select the application NSF (ls2011.nsf)
─ Right-Click > New > Source Folder
─
● Do not use Local as the source folder
─ Java files stored here are actually located on the
local workstation file system in the IBM® Lotus
Domino® Designer workspace and are not
inside the NSF file.
─ When XPages are compiled to Java classes, the
intermediate Java source file is written to here.
– Can be useful to examine these source
files to
© 2011 IBM Corporation
- 20. Simple CSV Data Source
● Create a new Source Folder
─ In the Folder name: field enter src
─ Select Finish
●
© 2011 IBM Corporation
- 21. Simple CSV Data Source
● Appropriate Java
Build Path is
automatically
configured
●
● Select src folder
─ Right-Click >
Build Path >
Configure Build
Path...
─ Select Libraries
tab
●
© 2011 IBM Corporation
- 22. Simple CSV Data Source
● Verify the src folder will
generate the class files
into the expected
location
(ls2011.nsf/WebContent/
WEB-INF/classes)
● Select src folder
─ Right-Click > Build
Path > Configure
Output Folder...
─
● Note: To see the classes
folder use the Navigator
view
─ Menu > Window >
Show Eclipse Views >
Navigator
© 2011 IBM Corporation
- 23. Simple CSV Data Source
● Create the a new Class file
─ Select the src folder
─ Right-Click > New > Class
●
© 2011 IBM Corporation
- 24. Simple CSV Data Source
● Enter the New Java Class details
─
─ Package:
– demo.ls2011.csv
─
─ Name:
– CSVDataSource
─
─ Superclass:
– com.ibm.xsp.model.AbstractDataSource
─
─ Interfaces:
– com.ibm.xsp.model.DataSource
─
─ Leave inherit abstract methods checked.
● Select Finish
© 2011 IBM Corporation
- 25. Simple CSV Data Source
● The CSV File Data
Source has 4 properties
─
─ csvFilePath
– location on the
local file system
─ separator
– field delimiter
–
─ firstLineIsHeader
– treat the first line
of the CSV file as
column headers.
–
─ trimWhiteSpace
– Postprocessing
the data, could be
anything you like © 2011 IBM Corporation
- 26. Simple CSV Data Source
● Theory: Literal values compared to Computed values
─
─ Property setter called for Literal values
– getter will simply return the set value
–
–
─ SetValueBinding called for Computed values
– Getter has to evaluate the corresponding value expression to
– AbstractDataSource.RuntimeProperties help optimize reading these values
●
© 2011 IBM Corporation
- 27. Simple CSV Data Source
● AbstractDataSource.RuntimeProperties
─
● Optimization to save recalculating computed properties
© 2011 IBM Corporation
- 28. Simple CSV Data Source
● Java Bean property accessors
─ Always follow this general structure
– If set directly, return the value
– Otherwise check for a computed value
● Specifies the location of the target CSV file
© 2011 IBM Corporation
- 29. Simple CSV Data Source
● Property accessors continued
●
● Allows developer specify the field delimiter
© 2011 IBM Corporation
- 30. Simple CSV Data Source
● Use this property to label columns
─ #{item.column2}
─
● With no header must specify column
position
─ #{item[1]}
© 2011 IBM Corporation
- 31. Simple CSV Data Source
● Can specify any other properties
required
─ Manipulation, transformation,
etc.
© 2011 IBM Corporation
- 32. Simple CSV Data Source
● UniqueId
─ Using a combination of the Data Source
properties, than can be repeatedly
calculated, construct an id to identity the
data souce, such that any property
changes that would effect the data would
generate a new id.
● Bean Id
─ The key used to store the DataContainer for the
DataSource
─ AbstractDataSource calculates beanId,
DataSource developer specified how to
compose the uniqueId
─ Default scope for DataSources is View Scope
─ If data shared
– scope = session
– scope = application
─ Then beanId = uniqueId © 2011 IBM Corporation
- 33. Simple CSV Data Source
● Abstract methods
─ Called by the XPages Framework to get the data from a data source
─
─
●
© 2011 IBM Corporation
- 34. Simple CSV Data Source
● Support changing functionality via request parameters
● http://server/app.nsf/csv.xsp?separator=:&firstLineIsHeader=false
─
●
● PrefixRequestParam
─ Enable request
parameters to be
specified for
individual data
sources
─
●
● Save is called by
XPages Framework if
Submit event was
triggered
© 2011 IBM Corporation
- 35. Simple CSV Data Source
● State Management
● StateHolder is a JSF interface that must be implemented by components
that need to save their state between requests
● Saving and restoring is done as a Serializable object
─ Must have a public no-args constructor
─
● Component tree is built for the initial request, and then restoring for
subsequent postbacks
● If it is not done right, components behave differently and data disappears in
subsequent POST requests after the initial GET
─
●
© 2011 IBM Corporation
- 36. Simple CSV Data Source
● State Management
●
● Must be Objects
●
● Care needed for primitive
types
●
●
●
●
● Ctrl-S to Save
© 2011 IBM Corporation
- 37. Simple CSV Data Source
● CSVRowData
─ Represents a row of data
●
● Implement DataObject
─ XPages Property Resolver knows about this
type
─ For EL expression like item.name instead of
calling getName() as is typical for Java Beans
the Property Resolver will call
getValue(“name”)
●
─ Is also implemented for DominoDocument
─ Similar to ViewRowData Interface used for row
data items in a Domino View.
─ Documentation Bug
– Interface com.ibm.xsp.model.DataObject is
not published.
© 2011 IBM Corporation
─
- 38. Simple CSV Data Source
● CSVRowData
─ Create a new Java Class
─
─ Package
– demo.ls2011.scv
–
─ Name
– CSVRowData
─
─ Interfaces
– com.ibm.xsp.model.
DataObject
– java.io.Serializable
●
© 2011 IBM Corporation
- 39. Simple CSV Data Source
● CSVRowData
●
●
●
●
●
●
●
● SerialVersionUID
─ not requied
─ added to remove warning
●
─
●
© 2011 IBM Corporation
- 40. Simple CSV Data Source
● Data Object
●
●
●
●
●
●
● GetValue()
─ #{item.name}
– gets the value for the field labeled “name”
–
─ #{item[2]}
– gets the value for the second field
– useful if CSV file doesn't use the first row to
specify column names
© 2011 IBM Corporation
–
- 41. Simple CSV Data Source
● DataObject
─
─ Data is stored in a Map of
key-value pairs
─
─
● CTRL-S to save
─
© 2011 IBM Corporation
- 42. Simple CSV Data Source
● In the Package Navigator, Select
the src folder, Right-Click
> New > Class to create a New
Java Class for the Data
Container
●
─ Package
– demo.ls2011.csv
–
─ Name:
– CSVDataContainer
–
─ Superclass:
– com.ibm.xsp.model.
AbstractDataContainer
●
● Select Finish © 2011 IBM Corporation
- 43. Simple CSV Data Source
● Data Container
─
● Data is a List of
CSVRowObjects
© 2011 IBM Corporation
- 44. Simple CSV Data Source
● Data Container
●
●
● Externalizable
─
●
© 2011 IBM Corporation
- 45. Simple CSV Data Source
● Data Container
●
●
● The actual implementation
to get the data
─
●
© 2011 IBM Corporation
- 47. Simple CSV Data Source
● Data Container
●
●
● Accessor methods to finish off the
Class
●
© 2011 IBM Corporation
- 48. Simple CSV Data Source
● Create the xsp-config file
●
●
●
─
●
© 2011 IBM Corporation
- 49. Simple CSV Data Source
● xsp-config
●
● New File
─ File name:
– csvDataSource.xsp-config
–
–
─
●
© 2011 IBM Corporation
- 50. Simple CSV Data Source
● Complex Types in the xsp-config file
─
─ Used to specify non-primative types in Xpages
– Objects
─ Represented using their own tags
─ Can specify a Class or Interface
●
─
●
© 2011 IBM Corporation
- 51. Simple CSV Data Source
● xsp-config
●
● Declare the namespace
● Descriptive information that
wil be used by Domino®
Designer
● The class the implements
the functionality and property
support
● Group-type-ref
─ Base data source
properties
─
●
© 2011 IBM Corporation
- 52. Simple CSV Data Source
● xsp-config
●
● Specify the required
properties
─
●
© 2011 IBM Corporation
- 53. Simple CSV Data Source
● xsp-config
●
● Properties
─
●
© 2011 IBM Corporation
- 54. Simple CSV Data Source
● Demo 2
─ Create the following test CSV files in the C: temp directory
●
─
●
© 2011 IBM Corporation
- 55. Simple CSV Data Source
● Demo 2
●
● Switch to the Domino Designer perspective
─ CTRL-F8 > Domino Designer
● Create a new Xpage called xpDemo1
─ XPages > New Xpage...
─ Name is xpDemo1
─ Select on the blank XPage design canvas so
the XPage design Properties tab appears
● In the XPage Properties tab
─ Open the Data section
─ Click Add and you will see CSV Data Source
in the drop down list
─
●
© 2011 IBM Corporation
- 56. Simple CSV Data Source
● Demo 2
●
● Declaratively configure the new data source
●
─
●
© 2011 IBM Corporation
- 58. Simple CSV Data Source
● Demo 2
●
● 2 single
row tables
with a
repeat
control
─
●
© 2011 IBM Corporation
- 59. Simple CSV Data Source
● Demo 3
●
●
●
● Create XPage with CSV Data Source
─
─ test3.csv
─ #SEP#
●
© 2011 IBM Corporation
- 60. Simple CSV Data Source
● Demo 3
●
● Create a Panel with a Repeat Control
●
● Create another Panel within the Repeat
●
● Configure a Data Source for this Panel
© 2011 IBM Corporation
- 61. Simple CSV Data Source
● Demo 3
─
● Properties for the inner Panel are computed
based on values read from the Data Source on
the XPage.
© 2011 IBM Corporation
- 62. Simple CSV Data Source
● Demo 3
─ Inner Repeat Iterates over a table row
© 2011 IBM Corporation
- 63. Simple CSV Data Source
● Demo 3
●
● Button performs partial refresh on outer Panel
when clicked.
─
─ Useful for testing data source State
Management
─
─ If is is wrong, data will disappear after
completion of the POST request
© 2011 IBM Corporation
- 64. Agenda
●Overview – options to connect to data
●The Data Source object model
●Setting up your development environment
●The first data source
●Debugging your code
●Connecting to RDBMS
●Connecting to Non relational data sources
●Deploying your data source
●Q &A
© 2011 IBM Corporation 64
- 65. Debugging you code
● Overview
─
─ Enable Java debugging on IBM® Lotus Domino®
●
─ Create a Debug Configuration
─
─
─
●
© 2011 IBM Corporation
- 66. Debugging you code
● Enable Java debugging on IBM® Lotus Domino® by adding the following
lines to notes.ini
─
─
─
─
─
─ JavaEnableDebug=1
─ JavaDebugOptions=transport=dt_socket,server=y,suspend=n,address=8
000
●
●
─
●
© 2011 IBM Corporation
- 67. Debugging you code
● Restart IBM® Lotus Domino® and verify that debugging has been enabled
by checking the server console for the following message:
– > Listening for transport dt_socket at address: 8000
– 1/01/2011 17:08:45 JVM: Java Virtual Machine initialized.
– 1/01/2011 17:08:45 HTTP Server: Java Virtual Machine loaded
─
─
─
─
●
© 2011 IBM Corporation
- 68. Debugging you code
● Instead of switching perspectives, stay in the Domino Designer perspective
and open the Navigator and Package Explorer views.
─ Window > Show Eclipse Views > Other...
─ Select Navigator (under General)
─ Click OK
─
─
─
─
●
© 2011 IBM Corporation
- 69. Debugging you code
● The Navigator opens be default
beside the Control palette and the
Data palette
●
● One benefit of the Navigator over the
Package Explorer is that the
Navigator show then compiled Java
classes for the application
●
● However it does not have the
Right-Click context menus for
configuring the Java build path
─
─
─
─
© 2011 IBM Corporation
- 70. Debugging you code
● To open the Package Explorer view:
─ Window > Show Eclipse Views > Other...
─ Select Package (under Java)
─ Click OK
─
─
─
─
●
© 2011 IBM Corporation
- 71. Debugging you code
● In Package Explorer, double-click on the class you are interested in
debugging to open it.
● Set a breakpoint in your code by double-clicking on the line number for the
method you want to debug.
● Notice a small circle icon will appear beside the line.
─
─
─
─
●
© 2011 IBM Corporation
- 72. Debugging you code
● Create a Debug
Configuration
●
● Select
─ Remote
Java
Application
─
─ Click New
─
─ Enter
– Name:
–
─ Leave all
other default
values
© 2011 IBM Corporation
─
- 73. Debugging you code
● Add your source
path to the debug
environment for
source code to
open for
breakpoints
●
● Select the source
tab
●
● Click Add
─
─
─
─
● © 2011 IBM Corporation
- 74. Debugging you code
● Choose
─ Java Project
─
● Select your project
─
─
─
─
─
●
© 2011 IBM Corporation
- 75. Debugging you code
● Click Apply
─ to save the
changes
─
● Click Debug to launch
the debugger
●
─
─
─
●
© 2011 IBM Corporation
- 77. Debugging you code
● The Java Debug perspective will open with the code stopped on the
breakpoint
─
─
─
─
●
© 2011 IBM Corporation
- 78. Summary
● Being able to debug custom code in an XPages application will be vital for
data source development
─
─
─
─
●
© 2011 IBM Corporation
- 79. Agenda
●Overview – options to connect to data
●The Data Source object model
●Setting up your development environment
●The first data source
●Debugging your code
●Connecting to RDBMS
●Connecting to Non relational data sources
●Deploying your data source
●Q &A
© 2011 IBM Corporation 79
- 80. Connecting to RDBMS
● Create a read only Data Source that allows a developer to declaratively
specify JDBC connection information and an SQL query that retrieves the
appropriate data
─
─
─
●
© 2011 IBM Corporation
- 81. Connecting to RDBMS
● Install DB2®
─ Include the sample databases
─ Assumes user is db2admin with password as password
─
● Locate the JDBC Type 4 driver
─ db2jcc.jar
─ db2jcc_license.jar
─ will need them later
─
─
─
─
●
© 2011 IBM Corporation
- 82. Connecting to RDBMS
● Create a simple helper class that
will be used to create database
connections
●
●
─
─
─
─
●
© 2011 IBM Corporation
- 88. Connecting to RDBMS
● Expected ClassNotFoundException
● Add the JDBC Driver to the NSF
─
─
─
─
●
© 2011 IBM Corporation
- 89. Connecting to RDBMS
● In the Java perspective, open
the Navigator
● Expand the
WebContent/WEB-INF folder
●
● Notice there is no lib folder
●
● Select WEB-INF
● Right-Click > New > Folder
─
─
─
─
●
© 2011 IBM Corporation
- 91. Connecting to RDBMS
● Select the lib folder under WebContent/WEB-INF
─
● Right-Click > Import...
●
© 2011 IBM Corporation
- 93. Connecting to RDBMS
● Browse to the folder that
contains the JDBC driver
● Select
─ db2jcc.jar
─ db2jcc_license.jar
─
● Click FInish
─
─
─
─
●
© 2011 IBM Corporation
- 94. Connecting to RDBMS
● JDBC Driver should be on the XPages
Classpath
●
●
●
●
●
● Run the test again
●
● Oooops...
─
─
─
─
© 2011 IBM Corporation
●
- 95. Connecting to RDBMS
● Check the logs
●
●
● Security Exception
─ checkPropertiesAccess() is not managed by AgentSecurityManager
─ Doesn't check if unrestriced users can perform the operation
─
─
─
─
─
● Need to move JDBC drivers to trusted location (since call is wrapped by
AccessController.doPrivileged() )
●
© 2011 IBM Corporation
- 96. Connecting to RDBMS
● C:Dominojvmlibsecurityjava.policy
●
●
●
● Choices:
●
─ Store JARs under C:Dominoxspshared
– it is a trusted location
– XPages ClassLoader will search for JARs here when runtime starts
─
─ Trust the specific NSF application as a location
●
© 2011 IBM Corporation
- 97. Connecting to RDBMS
● Restart the HTTP task to pick up changes to java.policy
─ tell http quit
─ load http
─
─ Rerun test
– success
─
─
─
●
© 2011 IBM Corporation
- 98. Connecting to RDBMS
● Create the
●
─ JDBC Query Data Source class
─
─ JDBC Query Data Container class
─
─ JDBC Query Data Source xsp-config configuration file
─
─
●
© 2011 IBM Corporation
- 99. Connecting to RDBMS
● Create new class
●
● Extend AbstractDataSource
─
─
─
─
●
© 2011 IBM Corporation
- 100. Connecting to RDBMS
● ComposeUniqueId()
─ Based on data source properties
─
● getDataObject()
─ return the data
●
● isReadOnly()
●
● ReadRequestParams()
─ data source specific options
●
● load()
─ Called by the XPages framework
● Save()
─ Called by the XPages framework © 2011 IBM Corporation
- 101. Connecting to RDBMS
● Define the properties the Data
Source is going to support
─
─
─
─
●
© 2011 IBM Corporation
- 102. Connecting to RDBMS
● Support Parameters - declared in the
xsp-config which then appear in the data
source property panel
─
─
─
─
●
© 2011 IBM Corporation
- 103. Connecting to RDBMS
● State Management for
primitive types
●
● Can't return null - need to
decide on value to be
returned when port is not set
─
─
─
─
●
© 2011 IBM Corporation
- 105. Connecting to RDBMS
● queryString holds the SQL
●
● In a form that will be parsed by a
JDBC PreparedStatement
─
─
─
─
●
© 2011 IBM Corporation
- 106. Connecting to RDBMS
● More property accessors
●
● KeyColumn could be used
to identify the Primary Key
column in the the table the
SQL query is based upon
─
─
─
─
●
© 2011 IBM Corporation
- 107. Connecting to RDBMS
● Override abstract methods
●
● Connection information and
SQL query.
─ Changing the sort order,
which still reads the data
from the same data source
could change the
UniqueId, triggering the
DataContainer to refresh
any cached data
●
● getDataObject gets the data
from the DataContainer
─
─
© 2011 IBM Corporation
─
- 108. Connecting to RDBMS
●
● load()
─ Called by
XPages
framework
●
●
●
●
● save()
─ Return false
since read
only
─
─
© 2011 IBM Corporation
─
- 110. Connecting to RDBMS
● JDBC Data Container
●
● Create a new class
●
● Extend
AbstractDataContainer
─
─
─
─
●
© 2011 IBM Corporation
- 111. Connecting to RDBMS
● JDBC Data Container
●
● DataContainers are not stored
with the DataSource in the
view
● The are managed by a scope
Bean Manager and are
identified by their beanId
─
─
─
─
●
© 2011 IBM Corporation
- 112. Connecting to RDBMS
● JDBC Data Container
●
● Get the data
●
● Other stragegy is to get the data
as part of the DataSource and just
have container manage its
lifecycle
─ Can it be cached
─ Does it need to be refereshed
─ Resource pooling
─
─
─
─
© 2011 IBM Corporation
●
- 113. Connecting to RDBMS
● JDBC Data Container
─
● JDBC code using ResultSet
─
─ Could consider RowSets
and have it handle
disconnected mode
─
─
●
© 2011 IBM Corporation
- 114. Connecting to RDBMS
● JDBC Data Container
─ Leverage FacesContextListener to manage the lifecycle of the data and
caching stratagies
– beforeRenderingPhase()
– beforeContextReleased()
─
─
─
─
●
© 2011 IBM Corporation
- 115. Connecting to RDBMS
● JDBC Data Container
─
─ Implements Externalizable
─
─ Class handles serialization
of each property itself
─
─ Optimization to avoid the
serialization code having
to intropsect and figure out
all the datatypes.
─
─
●
© 2011 IBM Corporation
- 116. Connecting to RDBMS
● Create ResultSetModelEx
●
─ Extends TabularDataModel
– better integration with
XPages Pager control for
ResultSets
─
─ Delegates to
ResultSetDataModel
─
─
─
●
© 2011 IBM Corporation
- 117. Connecting to RDBMS
● ResultSetModelEx
●
● Some properties and
constructors
●
● Wraps a ResultSetDataModel
to which it delegates most
methods, except
getRowCount() as we don't
want to return the standard -1
(prevents us working with the
pager controls. DataModels
that have an unknown count
can extend TabularDataModel
─
─
─ © 2011 IBM Corporation
- 118. Connecting to RDBMS
● ResultSetModelEx
●
● Pager estimates number
rows and ask data model if it
knows if rowCount is bigger
than current maxCount
●
● For the current page, always
return the current page
range + 1 – causes the
Pager to indicate that there
are more rows
─
─
─
─
© 2011 IBM Corporation
- 120. Connecting to RDBMS
● ResultSetModelEx
─
─ If isRowAvailable
returns false from the
delegated
ResultSetDataModel
then we know we have
found a potential value
for the actual row
count
─ HasMoreRows() will
start using this value
and since it will be less
than the current
deduced max in the
pager, it will readjust
based on this value.
─ © 2011 IBM Corporation
- 121. Connecting to RDBMS
● Create JDBC xsp-config
● Select WEB-INF, Right-Click > New > File
● File name:
─ jdbcQuertDataSource.xsp-config
●
─
─
─
─
●
© 2011 IBM Corporation
- 122. Connecting to RDBMS
● JDBC xsp-config
●
● Key property
─ complex-extension
– dataInterface
–
●
● If xsp-config file not
immediately recognised as
XML, close and reopen.
─
─
© 2011 IBM Corporation
- 123. Connecting to RDBMS
● JDBC Query Data Source
Properties
●
● Server
● Port
● Database
●
●
●
─
─
─
─
●
© 2011 IBM Corporation
- 124. Connecting to RDBMS
● JDBC Query Data Source
Properties
●
● User
● Password
●
● SQL query
●
─
─
─
─
●
© 2011 IBM Corporation
- 130. Connecting to RDBMS
● DataTable collection is called item
● Computed fields can bind to the data using EL expression
●
●
─
─
─
─
●
© 2011 IBM Corporation
- 131. Connecting to RDBMS
● Pager tries to
deduce last page
● ...Next indicates
more pages
●
● Keeps increasing
until no row is found,
then Pages adjusts
last page
● Next indicates a
max count found
●
●
●
─
─ © 2011 IBM Corporation
- 132. Agenda
●Overview – options to connect to data
●The Data Source object model
●Setting up your development environment
●The first data source
●Debugging your code
●Connecting to RDBMS (Part 2: CRUD)
●Connecting to Non relational data sources
●Deploying your data source
●Q &A
© 2011 IBM Corporation 132
- 134. Connecting to RDBMS(2)
● Create a JDBC Data Source that supports working with individual
rows in a table. Should support operations such as:
─
─ (C) inserting a new row
─ (R) selecting a specific row
─ (U) updating an existing row
─ (D) deleting a row
─
─
● Like a DominoView -> DominoDocument, Master -> Detail type relationship
●
─ JDBCQueryDataSource
– works with several rows
–
─ JDBCRecordDataSource
– works with a single row
© 2011 IBM Corporation
- 135. The JDBC Data Source Object Model
●
– AbstractDataSource
JDBCConstants
JDBCAbstractDataSource
JDBCUtil
JDBCRecordDataSource
JDBCConcurrencyInfo
AbstractDataContainer JDBCRecordDataContainer JDBCRecord
© 2011 IBM Corporation
- 136. The JDBC Data Source Object Model
●
– AbstractDataSource
JDBCConstants
JDBCAbstractDataSource
JDBCUtil
JDBCRecordDataSource
JDBCConcurrencyInfo
AbstractDataContainer JDBCRecordDataContainer JDBCRecord
© 2011 IBM Corporation
- 137. Connecting to RDBMS(2)
● Create a New Java Class
─ Select the ls2011 package
─ Right-Click, select
– New > Class
─
─
─
─
─
─
● Use CTRL-F8 to switch
perspectives (if necessary)
●
© 2011 IBM Corporation
- 138. Connecting to RDBMS(2)
● Create a New Java Class
●
● Package
─ demo.ls2011.jdbc4
─
● Name:
─ JDBCConstants
●
© 2011 IBM Corporation
- 139. Connecting to RDBMS(2)
● Constants
─ Not all used in current
implementation
─
─ JDBC Driver properties
─
─ Standard XPages (Domino
oriented URL parameters
─
─ Actions
– New, Open, Edit
●
© 2011 IBM Corporation
- 140. The JDBC Data Source Object Model
●
– AbstractDataSource
JDBCConstants
JDBCAbstractDataSource
JDBCUtil
JDBCRecordDataSource
JDBCConcurrencyInfo
AbstractDataContainer JDBCRecordDataContainer JDBCRecord
© 2011 IBM Corporation
- 141. Connecting to RDBMS(2)
● Create a New Java Class
●
● A class with helpful convenience
methods for working with JDBC,
e.g. open/close connections,
getting column information, setting
types, etc.
●
● Package:
─ demo.ls2011.jdbc4
─
● Name:
─ JDBCUtil
●
© 2011 IBM Corporation
- 142. Connecting to RDBMS(2)
● Open JDBC Connection
─
─ via Properties object
─
─ via basic properties
– server
– port
– database
– User
– password
●
© 2011 IBM Corporation
- 144. Connecting to RDBMS(2)
● More utility methods
─
─ Get a single
─
─ Get an empty ResultSet to
retirence the ResultSet meta
data to get column information
●
© 2011 IBM Corporation
- 145. Connecting to RDBMS(2)
● Utility method to for setting the
appropriate type for the columns when
setting parameters for a JDBC
PreparedStatement
●
─ not all types covered
– Numbers
– Characters
●
© 2011 IBM Corporation
- 146. The JDBC Data Source Object Model
●
– AbstractDataSource
JDBCConstants
JDBCAbstractDataSource
JDBCUtil
JDBCRecordDataSource
JDBCConcurrencyInfo
AbstractDataContainer JDBCRecordDataContainer JDBCRecord
© 2011 IBM Corporation
- 147. Connecting to RDBMS(2)
● Create a New Java Class
●
● Note
─ Use CTRL-Space to get
─ 'hints' on packages and
classes available in the
application package
hierarchy
─
●
© 2011 IBM Corporation
- 148. Connecting to RDBMS(2)
● Create a New Java Class
●
● Package:
─ demo.ls2011.jdbc4
─
● Name:
─ JDBCAbstractDataSource
●
● Modifiers:
─ public abstract
─
● Superclass:
─ com.ibm.xsp.model.Abstract
DataSource
●
© 2011 IBM Corporation
- 149. Connecting to RDBMS(2)
● Imports that can be added
as the abstract data source
class is developed
●
● Has the abstract modifier
●
● This class will be extended
later on with a concrete
class that will implement the
row oriented specifics of the
data source
●
●
© 2011 IBM Corporation
- 150. Connecting to RDBMS(2)
● Specify member variables that
represent properties for the
JDBC-based data source
─ server
─ port
─ database, etc
─
● parameters is as List
─ used to store name-value
(com.ibm.xsp.Paramster)
pairs that can be used to
pass information to the data
source.
─
●
●
© 2011 IBM Corporation
- 151. Connecting to RDBMS(2)
● Create property accessor methods
─ server
─ port
─
● Follow the standard 'template' for
getters
─ 1) check if instance variable is set
─ 2) check for a corresponding value
binding (if value can be computed)
─ 3) retrun null or default for primitive
(int etc.) types
●
● action
─ 'read only' property
─ set via request parameter
– action=newDocument © 2011 IBM Corporation
- 152. Connecting to RDBMS(2)
● More property accessors
─ database
─ user
● If RuntimeProperties is implmemented,
get it here.
●
● Extend the standard 'template' for
getters
─ 1) if using RuntimeProperties,
get it from there
─ 2) check if instance member
variable is set
─ 3) check for a corresponding value
binding (if the value can be
computed)
─ 4) retrun null or default for primitive
(int etc.) types © 2011 IBM Corporation
- 153. Connecting to RDBMS(2)
● More properties
─ password
─ selectString
●
● selectString
─ idea was that whether one row is
indented to be returned
(JDBCRecordDataSource), or
several (JDBCQueryDataSource).
─ oth have a SQL select statement in
common, so property is in abstract
class
– then decided to
modify/override with
concurrency column info (not
fully implemented)
● © 2011 IBM Corporation
- 154. Connecting to RDBMS(2)
● More properties
─ keyColumn
– primary key
–
─ tableName
– used for getting
database metadata
–
─ SortOrder
– not implemented.
●
● Optimize – collect metadata
during Connection/Data Source
definition
●
© 2011 IBM Corporation
- 155. Connecting to RDBMS(2)
●
● UniqueId
─ An identifier that distinguishes
this JDBC data source from
other JDBC data sources
– can be repeatedly
re-constructed form the
data source properties
─
─ used as the name for storing
data in scope (if shared)
─
─ connection information +
request parameter info + select
statement
© 2011 IBM Corporation
- 156. Connecting to RDBMS(2)
● Read general request
parameters
─ action
─ sortOrder
●
● Abstract methods sub-classes
must implement
─ isReadOnly()
─ getDataObject()
─ load()
─ save()
●
● Helper methods for connection
URL and opening the JDBC
connection
© 2011 IBM Corporation
- 157. Connecting to RDBMS(2)
● State Management for all the
properties
●
─ Handy StateHolderUtil
method for working with List
objects
●
●
© 2011 IBM Corporation
- 158. The JDBC Data Source Object Model
●
– AbstractDataSource
JDBCConstants
JDBCAbstractDataSource
JDBCUtil
JDBCRecordDataSource
JDBCConcurrencyInfo
AbstractDataContainer JDBCRecordDataContainer JDBCRecord
© 2011 IBM Corporation
- 159. Connecting to RDBMS(2)
● Next...
●
● create a helper class
JDBCConcurrencyInfo
●
─ Not really used. Keep in
mind that it (or this feature)
will be required for taking this
sample further for production
use.
●
●
© 2011 IBM Corporation
- 161. Connecting to RDBMS(2)
● Concurrency
─ Pessimistic
– RDBMS specific
─
─ Optimistic
– which column provides
the 'timestamp' that can
be compared for row
updates
–
─ Force
– Last Writer Wins
– Not really a good idea
●
●
© 2011 IBM Corporation
- 162. The JDBC Data Source Object Model
●
– AbstractDataSource
JDBCConstants
JDBCAbstractDataSource
JDBCUtil
JDBCRecordDataSource
JDBCConcurrencyInfo
AbstractDataContainer JDBCRecordDataContainer JDBCRecord
© 2011 IBM Corporation
- 163. Connecting to RDBMS(2)
● Next...
●
● Create a concrete class that implements
DataObject
─
─ JDBCRecord
●
● Purpose
─ Enables the data that are returned to
be simply referenced with an EL
expression using the data field/column
name
●
●
© 2011 IBM Corporation
- 164. Connecting to RDBMS(2)
● Create a New Java Class
●
● Name:
─ JDBCRecord
●
● Interfaces
─ com.ibm.xsp.model.
DataObject
– Known interface by the
XPages PropertyResolver,
calls getValue(“<prop>”)
─ java.io.Serializable
●
●
© 2011 IBM Corporation
- 165. Connecting to RDBMS(2)
● When the XPages Framework
calls
─ DataSource.getDataObject()
─ which in turn calls
─ DataContainer.getRecord()
● This is the returned object
● Is essentially the BackingBean
for the part of the UI that
displays the data from the Data
Source
●
● wrappedData
─ JDBC ResultSet
─ transient - not serializable
need to be managed
● © 2011 IBM Corporation
- 166. Connecting to RDBMS(2)
● Constructor
─ ResultSet
– wrapped
─ UniqueId
– Primary Key Column for
the record
─ Should be a List<String>
─
● Get the Column Types for each of
the Columns based on the
ResultSet meta data
●
● selectSQL
─ used to recreate the ResultSet
as necessary
● © 2011 IBM Corporation
- 167. Connecting to RDBMS(2)
●
● Implements the DataObject
methods:
●
─ getType(key)
─ getValue(key)
─ setValue(key,value)
─ isReadOnly()
●
© 2011 IBM Corporation
- 168. Connecting to RDBMS(2)
●
● The DataContainer
implementation will callback to
the JDBCRecord before and
after the de/serialized to give
JDBC an opportunity to do
anything it needs
●
© 2011 IBM Corporation
- 169. Connecting to RDBMS(2)
● discardWrappedObject
─ ResultSet is closed before
serialization.
─
─
● Several other methods not yet
fully implemented that will be
useful in the future:
─ CheckRecordValidity()
– row may been deleted
between requests
─
●
●
© 2011 IBM Corporation
- 170. The JDBC Data Source Object Model
●
– AbstractDataSource
JDBCConstants
JDBCAbstractDataSource
JDBCUtil
JDBCRecordDataSource
JDBCConcurrencyInfo
AbstractDataContainer JDBCRecordDataContainer JDBCRecord
© 2011 IBM Corporation
- 171. Connecting to RDBMS(2)
● Next...
●
● Create a concrete class that extends
AbstractDataContainer
─
─ JDBCRecordDataContainer
●
● Purpose
─ Manages the life-cycle of the data in a
stateless request response
environment
─ Good place for implementing a caching
strategy
●
●
© 2011 IBM Corporation
- 172. Connecting to RDBMS(2)
● Create a New Java Class
●
● Package:
─ demo.ls2011.jdbc4
─
● Name:
─ JDBCRecordDataContainer
─
● Superclass:
─ com.ibm.xsp.model.Abstract
DataContainer
●
●
© 2011 IBM Corporation
- 173. Connecting to RDBMS(2)
● com.ibm.xsp.model.Abstract
DataContainer
●
─ contains some basic support
for making the data source
Externalizable
●
● Need to implement the required
serialize and deserialize
methods
●
© 2011 IBM Corporation
- 174. Connecting to RDBMS(2)
●
● JDBCRecord
─ the data object
●
● FaceContectListener
─ used to discard
resources at the end of
the request
●
● In this implementation the
DataSource creates the
JDBCRecord and passes
it into the Constructor
●
© 2011 IBM Corporation
- 175. Connecting to RDBMS(2)
● FacesContextListener
─ Can use this listener to
manage the data
through the various
phases of the JSF
Lifecycle
─
●
●
● getRecord()
●
● Called from
DataSource.getDataObject()
– Xpages Framework
entry point for Data
Source data © 2011 IBM Corporation
- 176. Connecting to RDBMS(2)
● Externalizable
●
─ For Serialization when the
data to be serialized is
complex – since the datatype
are known can use the API
to specify the type avoid the
introspection
– readBoolean()
– readChar()
– readObject()
– ...
–
●
●
© 2011 IBM Corporation
- 177. The JDBC Data Source Object Model
●
– AbstractDataSource
JDBCConstants
JDBCAbstractDataSource
JDBCUtil
JDBCRecordDataSource
JDBCConcurrencyInfo
AbstractDataContainer JDBCRecordDataContainer JDBCRecord
© 2011 IBM Corporation
- 178. Connecting to RDBMS(2)
● Next...
● create a concrete
implementation that extends
JDBCAbstractDataSource
● that will work with a single row of
data in a table
●
● It will support operations to
─ (C)reate -> Insert
─ (R)ead -> Select
─ (U)pdate -> Update
─ (D)elete-> Delete
●
●
© 2011 IBM Corporation
- 179. Connecting to RDBMS(2)
● Create a New Java Class
●
● Package:
─ demo.ls2011.jdbc4
─
● Name
─ JDBCRecordDataSource
●
● Superclass:
─ demo.ls2011.jdbc4.
JDBCAbstractDataSource
●
© 2011 IBM Corporation
- 180. Connecting to RDBMS(2)
● Required imports
●
● JDBCRecordDataSource
specifies the SQL required for
manipulating the data
●
● MethodBinding
─ Support actions that can be
called before and after
saving row
●
●
© 2011 IBM Corporation
- 181. Connecting to RDBMS(2)
● Property setter and getters
●
● Check if the value has been set,
otherwise check for a computed
value
●
●
© 2011 IBM Corporation
- 183. Connecting to RDBMS(2)
● More properties...
●
● recordId is the PK
●
●
●
●
● isReadOnly()
─
● isNewRecord()
─ Depends on the action
– newDocument
●
© 2011 IBM Corporation
- 184. Connecting to RDBMS(2)
● If no action is specified,
assumes newDocument
●
● Whenever the XPages
component tree is being
constructed or traversed any
data controls are 'published'
●
● DataPublisher() calls
getDataObject()
● getDataContainer() is
implemented in
AbstractDataSource
─ checks uniqueId()
─ calls load()
● © 2011 IBM Corporation
- 185. Connecting to RDBMS(2)
● Save is triggered by the
XspCommandButton
─ save=true
─
● invoke preSave
─ false prevents save
● doSave
● Invoke postSave
●
●
●
© 2011 IBM Corporation
- 186. Connecting to RDBMS(2)
● Invoke the Data Source Action
─ push()
─ invoke()
─ pop()
●
● If it's a new document, then
beforehand, for example,
queryNewDocument, there is
no record/document, so no
data to push to request scope,
so in this case, record would
be null.
●
© 2011 IBM Corporation
- 187. Connecting to RDBMS(2)
● Read JDBCRecordDataSource
specific request parameters
●
● JDBCConstants
─ URL_PARAM_ID
– documentId
●
● DataSource will be published
using the var attribute
─ record1
● Can publish the data using
several identifiers,
─ currentDocument
─
© 2011 IBM Corporation
- 188. Connecting to RDBMS(2)
● (C)reate
●
● an 'empty' result set for the
column meta data
●
● returns a JDBCDataContainer
●
●
●
● Concurrency not yet
implemented
●
© 2011 IBM Corporation
- 189. Connecting to RDBMS(2)
● (R)ead
●
● JDBC PreparedStatement
●
● If documentId not set in
URL, or ignoring request
parameters for this data
source look into the supplied
Parameters
●
●
● If asked to read a row, but
no PK specified, default to
Create/Insert a new row
© 2011 IBM Corporation
- 192. Connecting to RDBMS(2)
● (U)pdate
─ if openDocument
─
● (C)reate
─ if newDocument
●
●
● work with the JDBCRecord
●
●
© 2011 IBM Corporation
- 193. Connecting to RDBMS(2)
● SQL INSERT or UPDATE
statement needed?
●
●
● Specify the Prepared
Statement parameters using
the appropriate type of each
column
●
●
© 2011 IBM Corporation
- 194. Connecting to RDBMS(2)
● For UPDATE, the PK value
should be specified in the
WHERE clause
●
●
●
● executeUpdate()
─ should update/insert 1 row
●
●
● If it was INSERT – get the PK
value so it can be stored in the
JDBCRecord
●
● © 2011 IBM Corporation
- 196. Connecting to RDBMS(2)
● StateManagement
─ as always!
─
─
● Note the StateHolderUtil
helper mehtods
─ saveMethodBinding()
─ restoreMethodBinding()
●
●
© 2011 IBM Corporation
- 198. Connecting to RDBMS(2)
● Next...
●
● Create an XPages .xsp-config
file that defines the properties
and Domino Designer
integration.
●
●
© 2011 IBM Corporation
- 199. Connecting to RDBMS(2)
●
–
com.ibm.xsp.model.group
AbstractDataSource
.DataSource
JDBCAbstractDataSource jdbcAbstractDataSource.xsp-config
JDBCRecordDataSource jdbcRecordDataSource.xsp-config
© 2011 IBM Corporation
- 200. Connecting to RDBMS(2)
● Still in the Java Perspective
●
● Under
─ WebContent /
– WEB-INF
●
●
© 2011 IBM Corporation
- 202. Connecting to RDBMS(2)
● Create a New File
●
● File name:
─ jdbcAbstractDataSource.
xsp-config
●
●
© 2011 IBM Corporation
- 203. Connecting to RDBMS(2)
● Define a <group>
─ idenfifed by <group-type>
─
● specify all the properties
declared in
JDBCAbstractDataSource
●
─ server
─ port
─ database
─
●
●
© 2011 IBM Corporation
- 204. Connecting to RDBMS(2)
● More properties.....
●
─ user
─ password
─ selectString
─ tableName
─
●
●
●
© 2011 IBM Corporation
- 205. Connecting to RDBMS(2)
● More properties.....
●
─ keyColumn
─ parameters
– <property-class>
●
ArrayList
– <collection-property>
●
true
© 2011 IBM Corporation
- 207. Connecting to RDBMS(2)
● <complex-type>
─ specifes an Object with
properties
● <display-name>
─ will be shown in Domino
Designer
● <complex-id>
─ identifier
─
● <complex-class>
─ fully qualified implementing
class
●
●
© 2011 IBM Corporation
- 208. Connecting to RDBMS(2)
● More properties....
●
●
●
● <property-class>
─ javax.faces.el.MethodBinding
─
● <property-extension>
─ DominoDesigner directive
─ <method-binding-property>
– true
© 2011 IBM Corporation
- 209. Connecting to RDBMS(2)
● <group-type-ref>
─ to include properties from
other .xsp-config definition
files
─
● <complex-extension>
─ <tag-name>
– jdbcRecordDataSource
─ <base-complex-id>
– dataInterface
●
●
© 2011 IBM Corporation
- 216. Connecting to RDBMS(2)
● Data source events can be
added
●
─ Although they show up
in the Data Events tab
─ add them as a property
of the Data Source
●
●
© 2011 IBM Corporation
- 223. Connecting to RDBMS(2)
● Update xpDemo4 to include
command link and command
button to open xpDemo5 with
row details
●
●
© 2011 IBM Corporation
- 225. Connecting to RDBMS(2)
● Will add the request parameters
─ action=openDocument&documentId=<item.empno>
●
●
© 2011 IBM Corporation
- 228. Agenda
●Overview – options to connect to data
●The Data Source object model
●Setting up your development environment
●The first data source
●Debugging your code
●Connecting to RDBMS
●Connecting to Non relational data sources
●Deploying your data source
●Q &A
© 2011 IBM Corporation 228
- 229. Connecting to non relational data sources
● XML
● Web Services (REST/SOAP)
● etc
●
● Same approach as two previous examples
●
● Extend AbstractDataSource to define what properties the data
source has
●
● Extend AbstractDataContainer to manage the life-cycle of the
data in the context of a disconnected web application where the
data is only live for the duration of the request
●
●
© 2011 IBM Corporation
─
- 230. Agenda
●Overview – options to connect to data
●The Data Source object model
●Setting up your development environment
●The first data source
●Debugging your code
●Connecting to RDBMS
●Connecting to Non relational data sources
●Deploying your data source
●Q &A
© 2011 IBM Corporation 230
- 231. Deploying your data source
● To create a sharable library (OSGi Plugin), see
─
─ http://www-10.lotus.com/ldd/ddwiki.nsf/dx/Creating_an_XPag
es_Library
●
● For deployment on Lotus Domino® and Lotus Notes® Client, see
─
─ http://www-10.lotus.com/ldd/ddwiki.nsf/dx/Deploying_XPage_
Libraries
─
─
─
─
●
© 2011 IBM Corporation
- 232. Agenda
●Overview – options to connect to data
●The Data Source object model
●Setting up your development environment
●The first data source
●Debugging your code
●Connecting to RDBMS
●Connecting to Non relational data sources
●Deploying your data source
●Q &A
© 2011 IBM Corporation 232
- 233. Q&A for General XPages Development
●
●
●
●
●
●
●
●
●
●
● blog.sequill.com
─ connect to development, general Xpages developemnt
●
© 2011 IBM Corporation
- 234. Mastering XPages
●
Factoids ...
─ Comprehensive 7 Part, 785 page volume
─ IBM Press publication
─ Authored by lead members of XPages development team
─ Features contributions from other key community members
─ Covers all aspects of XPages application development
─ Example-driven approach focusing on practical problems
─ Includes sample NSF downloads
● Available now @ Lotusphere bookstore
● Available online
─ www.ibmpressbooks.com/bookstore/product.asp?isbn=0132486482
─ www.amazon.com/Mastering-XPages-Step-Step-Application/dp/0132486318
234 © 2011 IBM Corporation
- 235. Q&A
●We ask you answer!
© 2011 IBM Corporation
- 238. Q&A
●Now it is your turn!
© 2011 IBM Corporation
- 239. Legal Disclaimer
© IBM Corporation 2011. All Rights Reserved.
The information contained in this publication is provided for informational purposes only. While efforts were made to verify the completeness and accuracy of the information contained in this publication, it is provided AS IS without
warranty of any kind, express or implied. In addition, this information is based on IBM’s current product plans and strategy, which are subject to change by IBM without notice. IBM shall not be responsible for any damages arising out
of the use of, or otherwise related to, this publication or any other materials. Nothing contained in this publication is intended to, nor shall have the effect of, creating any warranties or representations from IBM or its suppliers or
licensors, or altering the terms and conditions of the applicable license agreement governing the use of IBM software.
References in this presentation to IBM products, programs, or services do not imply that they will be available in all countries in which IBM operates. Product release dates and/or capabilities referenced in this presentation may change
at any time at IBM’s sole discretion based on market opportunities or other factors, and are not intended to be a commitment to future product or feature availability in any way. Nothing contained in these materials is intended to, nor
shall have the effect of, stating or implying that any activities undertaken by you will result in any specific sales, revenue growth or other results.
IBM, the IBM logo, Lotus, Lotus Notes, Notes, Domino, and Lotusphere are trademarks of International Business Machines Corporation in the United States, other countries, or both. Unyte is a trademark of WebDialogs, Inc., in the
United States, other countries, or both.
Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
© 2011 IBM Corporation 239
- 240. SHOW107 The Data Source
Session: Take XPages data
boldly where no XPages data
has been taken before
Jim Quill | XPages Developer | IBM Ireland
Stephan H. Wissel | LTPA | IBM Singapore
© 2011 IBM Corporation
- 241. Agenda
●Overview – options to connect to data
●The Data Source object model
●Setting up your development environment
●Simple CSV file Data Source
●Debugging your code
●Connecting to RDBMS
●Connecting to Non relational data sources
●Deploying your data source
●Q &A
© 2011 IBM Corporation 2
- 242. Overview – options to connect to data
● Built-in DataSources
─ Domino® View
─ Domino® Document
─
● SeverSide JavaScript
─ Write custom Java™ code to connect any data source and return that data
as an object, array, List, ResultSet, or DataModel will enable XPages
controls to consume that data.
─
● Any control that holds data, for display or editing can be bound to an item of
data, a field in a Domino document or a property of a Managed Bean, for
example.
●
● Container controls, i.e. DataTable, Repeat, and View Panel can be bound to a
single item or a collection of items and will iterate over the data
–
© 2011 IBM Corporation
- 243. Overview – options to connect to data
● Demo 1
─ Create an array
─ Put it into view
scope
─ Reference data
using EL
expression
─
●
© 2011 IBM Corporation
- 244. Overview – options to connect to data
● Built-in DataSources Benefits
─
─ declaratively add and reuse custom data sources to an XPage,
─
─ computed properties
─
─ easy access the data souce in SSJS
─
─ nest DataSources so contents of one data source can be bound to
computed properties of another data source defined on an inner panel that
is in a Repeat control
─
─ control behavoiur via URL parameters
─
─ add your own query/postSaveEvents, and more
© 2011 IBM Corporation
- 245. Overview – options to connect to data
● Objectives for todays session
─
─ Write a data source that
reads a CSV file from the
local filesystem
─
─
─
─
─ Write a data source that
reads data from an RDBMS
by executing SQL via JDBC
–
●
●
─
© 2011 IBM Corporation
─
─
─
●
- 246. Agenda
●Overview – options to connect to data
●The Data Source object model
●Setting up your development environment
●The first data source
●Debugging your code
●Connecting to RDBMS
●Connecting to Non relational data sources
●Deploying your data source
●Q &A
© 2011 IBM Corporation 7
- 247. The Data Source Object Model
● For the two core storage artifacts, View and Documents, XPages provides a
convenient mechanism to declaratively add these two data sources to your
application without any coding
─ All properties can be computed using JavaScript or an EL expression
─ Tight integration with a set of easy to use Simple Actions for working with
Documents and View
─ Ability to specify request parameters to control and influence the behavior
of the data source
●
● Within the XPages framework, data sources are based on two key classes
─ com.ibm.xsp.model.AbstractDataSource
─ com.ibm.xsp.model.AbstractDataContainer
─
–
© 2011 IBM Corporation
- 248. The Data Source Object Model
●
─
ComponentBindingObject ValueBindingObject
–
DataPublishingObject Externalizable
StateHolder DataContainer
DataSource
AbstractDataSource AbstractDataContainer
© 2011 IBM Corporation
- 249. The Data Source Object Model
● AbstractDataSource Responsibilities
─ Data source id management
– BeanId
– UniqueId
─ RuntimeProperty management
– Computed properties can be saved as runtime property so its values
doesn't have to be repeatedly calculated
─ State Management
– Base properties var, scope, ignoreRequestParams,
requestParamPrefix
– Property accessors for state of component to be recreated
─ Data Container Management
─ DataPublishing
– pushData, popData – publishes the DataModel to request scope using
the specified var attribute as the key
●
© 2011 IBM Corporation
- 250. The Data Source Object Model
● Data Container Responsibilities
─ Externalizable support
─ Manages the life cycle of the data – if it doesn't continuously store the data
between requests, it knows how to retrieve it.
─
─
●
© 2011 IBM Corporation
- 251. Agenda
●Overview – options to connect to data
●The Data Source object model
●Setting up your development environment
●The first data source
●Debugging your code
●Connecting to RDBMS
●Connecting to Non relational data sources
●Deploying your data source
●Q &A
© 2011 IBM Corporation 12
- 252. Setting up your development environment
● What you need
─ IBM® Lotus Domino® Designer 8.5.2
─ IBM® Lotus Domino® 8.5.2
─ IBM® DB2®
─
─
● What you should have to hand:
─ Javadoc
– XPages Extensibility API Documentation
– http://www-10.lotus.com/ldd/ddwiki.nsf/dx/XPages_Extensibility_API_Document
ation
─
─ Wiki
– XPages Extensibility API Developers Guide
– http://www-10.lotus.com/ldd/ddwiki.nsf/dx/Master_Table_of_Contents_for_XPag
es_Extensibility_APIs_Developer_Guide
● © 2011 IBM Corporation
- 253. Agenda
●Overview – options to connect to data
●The Data Source object model
●Setting up your development environment
●Simple CSV File Data Source
●Debugging your code
●Connecting to RDBMS
●Connecting to Non relational data sources
●Deploying your data source
●Q &A
© 2011 IBM Corporation 14
- 254. Simple CSV Data Source
● Create a New Application
─ Menu > File > New
●
© 2011 IBM Corporation
- 255. Simple CSV Data Source
● Overview
─ Create a New Application
─ Project setup
─ Extend AbstractDataSource
– Manages the DataSource properties
─ Extend AbstractDataContainer
– Manages the Data life cycle, caching, refreshing
─ Create an xsp-config file that describes the DataSource so it can integrate
with Lotus Domino® Designer and the Xpages Framework
●
●
© 2011 IBM Corporation
- 256. Simple CSV Data Source
● Application Setup
─ Grant Anonymous Manager access level File > Application > Access Control...
─ Specify oneuiv2 as the Web theme. File > Application > Properties > Xpages
─ CTRL-S to save changes
© 2011 IBM Corporation
- 257. Simple CSV Data Source
● Switch to the Java™ perspective
─ Window > Open Perspective > Java
●
● Shortcut
─ CTRL-F8
●
●
● A virtual file system for the NSF
─ organized like a WAR
© 2011 IBM Corporation
- 258. Simple CSV Data Source
● Create a new Source Folder
─ Select the application NSF (ls2011.nsf)
─ Right-Click > New > Source Folder
─
● Do not use Local as the source folder
─ Java files stored here are actually located on the
local workstation file system in the IBM® Lotus
Domino® Designer workspace and are not
inside the NSF file.
─ When XPages are compiled to Java classes, the
intermediate Java source file is written to here.
– Can be useful to examine these source
files to
© 2011 IBM Corporation
- 259. Simple CSV Data Source
● Create a new Source Folder
─ In the Folder name: field enter src
─ Select Finish
●
© 2011 IBM Corporation
- 260. Simple CSV Data Source
● Appropriate Java
Build Path is
automatically
configured
●
● Select src folder
─ Right-Click >
Build Path >
Configure Build
Path...
─ Select Libraries
tab
●
© 2011 IBM Corporation
- 261. Simple CSV Data Source
● Verify the src folder will
generate the class files
into the expected
location
(ls2011.nsf/WebContent/
WEB-INF/classes)
● Select src folder
─ Right-Click > Build
Path > Configure
Output Folder...
─
● Note: To see the classes
folder use the Navigator
view
─ Menu > Window >
Show Eclipse Views >
Navigator
© 2011 IBM Corporation
- 262. Simple CSV Data Source
● Create the a new Class file
─ Select the src folder
─ Right-Click > New > Class
●
© 2011 IBM Corporation
- 263. Simple CSV Data Source
● Enter the New Java Class details
─
─ Package:
– demo.ls2011.csv
─
─ Name:
– CSVDataSource
─
─ Superclass:
– com.ibm.xsp.model.AbstractDataSource
─
─ Interfaces:
– com.ibm.xsp.model.DataSource
─
─ Leave inherit abstract methods checked.
● Select Finish
© 2011 IBM Corporation
- 264. Simple CSV Data Source
● The CSV File Data
Source has 4 properties
─
─ csvFilePath
– location on the
local file system
─ separator
– field delimiter
–
─ firstLineIsHeader
– treat the first line
of the CSV file as
column headers.
–
─ trimWhiteSpace
– Postprocessing
the data, could be
anything you like © 2011 IBM Corporation
- 265. Simple CSV Data Source
● Theory: Literal values compared to Computed values
─
─ Property setter called for Literal values
– getter will simply return the set value
–
–
─ SetValueBinding called for Computed values
– Getter has to evaluate the corresponding value expression to
– AbstractDataSource.RuntimeProperties help optimize reading these values
●
© 2011 IBM Corporation
- 266. Simple CSV Data Source
● AbstractDataSource.RuntimeProperties
─
● Optimization to save recalculating computed properties
© 2011 IBM Corporation
- 267. Simple CSV Data Source
● Java Bean property accessors
─ Always follow this general structure
– If set directly, return the value
– Otherwise check for a computed value
● Specifies the location of the target CSV file
© 2011 IBM Corporation
- 268. Simple CSV Data Source
● Property accessors continued
●
● Allows developer specify the field delimiter
© 2011 IBM Corporation
- 269. Simple CSV Data Source
● Use this property to label columns
─ #{item.column2}
─
● With no header must specify column
position
─ #{item[1]}
© 2011 IBM Corporation
- 270. Simple CSV Data Source
● Can specify any other properties
required
─ Manipulation, transformation,
etc.
© 2011 IBM Corporation
- 271. Simple CSV Data Source
● UniqueId
─ Using a combination of the Data Source
properties, than can be repeatedly
calculated, construct an id to identity the
data souce, such that any property
changes that would effect the data would
generate a new id.
● Bean Id
─ The key used to store the DataContainer for the
DataSource
─ AbstractDataSource calculates beanId,
DataSource developer specified how to
compose the uniqueId
─ Default scope for DataSources is View Scope
─ If data shared
– scope = session
– scope = application
─ Then beanId = uniqueId © 2011 IBM Corporation
- 272. Simple CSV Data Source
● Abstract methods
─ Called by the XPages Framework to get the data from a data source
─
─
●
© 2011 IBM Corporation
- 273. Simple CSV Data Source
● Support changing functionality via request parameters
● http://server/app.nsf/csv.xsp?separator=:&firstLineIsHeader=false
─
●
● PrefixRequestParam
─ Enable request
parameters to be
specified for
individual data
sources
─
●
● Save is called by
XPages Framework if
Submit event was
triggered
© 2011 IBM Corporation
- 274. Simple CSV Data Source
● State Management
● StateHolder is a JSF interface that must be implemented by components
that need to save their state between requests
● Saving and restoring is done as a Serializable object
─ Must have a public no-args constructor
─
● Component tree is built for the initial request, and then restoring for
subsequent postbacks
● If it is not done right, components behave differently and data disappears in
subsequent POST requests after the initial GET
─
●
© 2011 IBM Corporation
- 275. Simple CSV Data Source
● State Management
●
● Must be Objects
●
● Care needed for primitive
types
●
●
●
●
● Ctrl-S to Save
© 2011 IBM Corporation
- 276. Simple CSV Data Source
● CSVRowData
─ Represents a row of data
●
● Implement DataObject
─ XPages Property Resolver knows about this
type
─ For EL expression like item.name instead of
calling getName() as is typical for Java Beans
the Property Resolver will call
getValue(“name”)
●
─ Is also implemented for DominoDocument
─ Similar to ViewRowData Interface used for row
data items in a Domino View.
─ Documentation Bug
– Interface com.ibm.xsp.model.DataObject is
not published.
© 2011 IBM Corporation
─
●