SHOW107: The DataSource Session: Take XPages data boldly where no XPages data has been taken before

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

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

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
–

● Demo 1
─ Create an array
─ Put it into view
scope
─ Reference data
using EL
expression
─

●


● 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

● Objectives for todays session
─
─ Write a data source that
reads a CSV file from the
local filesystem
─
─
─
─
reads data from an RDBMS
by executing SQL via JDBC
–

●

●
─

Agenda



●The first data source





●Q &A


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
─
–


●
─
ComponentBindingObject ValueBindingObject
–

DataPublishingObject Externalizable

StateHolder DataContainer

DataSource

AbstractDataSource AbstractDataContainer


● 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
●

● 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.
─
─

●


Agenda








●Q &A


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

Agenda



●Simple CSV File Data Source





●Q &A


Simple CSV Data Source
● Create a New Application
─ Menu > File > New
●


● 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
●

●


● 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


● Switch to the Java™ perspective
─ Window > Open Perspective > Java
●

● Shortcut
─ CTRL-F8
●

●

● A virtual file system for the NSF
─ organized like a WAR


● 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


● Create a new Source Folder
─ In the Folder name: field enter src
─ Select Finish
●


● Appropriate Java
Build Path is
automatically
configured
●

● Select src folder
─ Right-Click >
Build Path >
Configure Build
Path...
─ Select Libraries
tab
●


● 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

● Create the a new Class file
─ Select the src folder
─ Right-Click > New > Class
●


● 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

● 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

● 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

●


● AbstractDataSource.RuntimeProperties
─

● Optimization to save recalculating computed properties


● 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


● Property accessors continued
●

● Allows developer specify the field delimiter


● Use this property to label columns
─ #{item.column2}
─

● With no header must specify column
position
─ #{item[1]}


● Can specify any other properties
required
─ Manipulation, transformation,
etc.


● 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

● Abstract methods
─ Called by the XPages Framework to get the data from a 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

● 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
─

●


● State Management
●

● Must be Objects
●

● Care needed for primitive
types
●

●

●

●

● Ctrl-S to Save


● 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.
─

● CSVRowData
─ Create a new Java Class
─
─ Package
– demo.ls2011.scv
–

─ Name
– CSVRowData

─
─ Interfaces
– com.ibm.xsp.model.
DataObject
– java.io.Serializable

●


● CSVRowData
●

●

●

●

●

●

●

● SerialVersionUID
─ not requied
─ added to remove warning
●
─

●

● 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
–

● DataObject
─

─ Data is stored in a Map of
key-value pairs
─
─

● CTRL-S to save
─


● 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

● Data Container
─

● Data is a List of
CSVRowObjects


● Data Container
●

●

● Externalizable
─

●


● Data Container
●

●

● The actual implementation
to get the data
─

●


● Data Container
─

●


● Data Container
●

●

● Accessor methods to finish off the
Class
●


● Create the xsp-config file
●

●

●
─

●


● xsp-config
●

● New File
─ File name:
– csvDataSource.xsp-config
–
–

─

●


● 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
●
─

●


● 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
─

●


● xsp-config
●

● Specify the required
properties
─

●


● xsp-config
●

● Properties
─

●


● Demo 2
─ Create the following test CSV files in the C: temp directory
●
─

●


● 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
─

●


● Demo 2
●

● Declaratively configure the new data source
●
─

●


● Demo 2
─

●


● Demo 2
●

● 2 single
row tables
with a
repeat
control
─

●


● Demo 3
●

●

●

● Create XPage with CSV Data Source
─
─ test3.csv
─ #SEP#
●


● Demo 3
●

● Create a Panel with a Repeat Control
●

● Create another Panel within the Repeat
●

● Configure a Data Source for this Panel


● Demo 3
─

● Properties for the inner Panel are computed
based on values read from the Data Source on
the XPage.


● Demo 3
─ Inner Repeat Iterates over a table row


● 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


Agenda








●Q &A


Debugging you code
● Overview
─
─ Enable Java debugging on IBM® Lotus Domino®
●
─ Create a Debug Configuration
─
─
─

●


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
●

●
─

●


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
─
─
─
─

●


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
─
─
─
─

●


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
─
─
─
─

Debugging you code
● To open the Package Explorer view:
─ Window > Show Eclipse Views > Other...
─ Select Package (under Java)
─ Click OK
─
─
─
─

●


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.
─
─
─
─

●


Debugging you code
● Create a Debug
Configuration
●

● Select
─ Remote
Java
Application
─
─ Click New
─
─ Enter
– Name:
–
─ Leave all
other default
values
─

Debugging you code
● Add your source
path to the debug
environment for
source code to
open for
breakpoints
●

● Select the source
tab
●

● Click Add
─
─
─
─


Debugging you code
● Choose
─ Java Project
─

● Select your project
─
─
─
─
─

●


Debugging you code
● Click Apply
─ to save the
changes
─

● Click Debug to launch
the debugger
●
─
─
─

●


Debugging you code
● Run the demo XPage application again
─
─
─
─

●


Debugging you code
● The Java Debug perspective will open with the code stopped on the
breakpoint
─
─
─
─

●


Summary
● Being able to debug custom code in an XPages application will be vital for
data source development
─
─
─
─

●


Agenda








●Q &A


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
─
─
─

●


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
─
─
─
─

●


Connecting to RDBMS
● Create a simple helper class that
will be used to create database
connections
●

●
─
─
─
─

●


Connecting to RDBMS
● Only supports DB2® driver
protocol
●
─
─
─
─

●


Connecting to RDBMS
● Code to load the
JDBC driver
─
─
─
─

●


Connecting to RDBMS
● Test the connection and configuration
─
─
─
─

●


Connecting to RDBMS
● Simple test application
─
─
─
─

●


Connecting to RDBMS
● SSJS to call the static test method
─
─
─
─

●


Connecting to RDBMS
● Expected ClassNotFoundException
● Add the JDBC Driver to the NSF
─
─
─
─

●


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
─
─
─
─

●


Connecting to RDBMS
● Folder name:
─ lib

●

● Click Finish
─
─
─
─

●


Connecting to RDBMS
● Select the lib folder under WebContent/WEB-INF
─

● Right-Click > Import...
●


Connecting to RDBMS
● Select File System
●

● Click Next
─
─
─
─

●


Connecting to RDBMS
● Browse to the folder that
contains the JDBC driver
● Select
─ db2jcc.jar
─ db2jcc_license.jar
─

● Click FInish
─
─
─
─

●


Connecting to RDBMS
● JDBC Driver should be on the XPages
Classpath
●

●

●

●

●

● Run the test again
●

● Oooops...
─
─
─
─
●

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() )
●


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
●


Connecting to RDBMS
● Restart the HTTP task to pick up changes to java.policy
─ tell http quit
─ load http
─
─ Rerun test
– success
─
─
─

●


Connecting to RDBMS
● Create the
●
─ JDBC Query Data Source class
─
─ JDBC Query Data Container class
─
─ JDBC Query Data Source xsp-config configuration file
─
─

●


Connecting to RDBMS
● Create new class
●

● Extend AbstractDataSource
─
─
─
─

●


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

Connecting to RDBMS
● Define the properties the Data
Source is going to support
─
─
─
─

●


Connecting to RDBMS
● Support Parameters - declared in the
xsp-config which then appear in the data
source property panel
─
─
─
─

●


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
─
─
─
─

●


Connecting to RDBMS
● If using RuntimeProperties,
check here
─
─
─
─

●


Connecting to RDBMS
● queryString holds the SQL
●

● In a form that will be parsed by a
JDBC PreparedStatement
─
─
─
─

●


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
─
─
─
─

●


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
─
─
─

Connecting to RDBMS
●

● load()
─ Called by
XPages
framework
●

●

●

●

● save()
─ Return false
since read
only
─
─
─

Connecting to RDBMS
● State management
─
─
─
─

●


Connecting to RDBMS
● JDBC Data Container
●

● Create a new class
●

● Extend
─
─
─
─

●


Connecting to RDBMS
●

● DataContainers are not stored
with the DataSource in the
view
● The are managed by a scope
Bean Manager and are
identified by their beanId
─
─
─
─

●


Connecting to RDBMS
●

● 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
─
─
─
─
●

Connecting to RDBMS
─

● JDBC code using ResultSet
─
─ Could consider RowSets
and have it handle
disconnected mode
─
─

●


Connecting to RDBMS
─ Leverage FacesContextListener to manage the lifecycle of the data and
caching stratagies
– beforeRenderingPhase()
– beforeContextReleased()
─
─
─
─

●


Connecting to RDBMS
─
─ Implements Externalizable
─
─ Class handles serialization
of each property itself
─
─ Optimization to avoid the
serialization code having
to intropsect and figure out
all the datatypes.
─
─

●


Connecting to RDBMS
● Create ResultSetModelEx
●
─ Extends TabularDataModel
– better integration with
XPages Pager control for
ResultSets
─
─ Delegates to
ResultSetDataModel
─
─
─

●


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

Connecting to RDBMS
●

● 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
─
─
─
─

Connecting to RDBMS
●

● Delegated methods
─
─
─
─

●


Connecting to RDBMS
─
─ 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.

Connecting to RDBMS
● Create JDBC xsp-config
● Select WEB-INF, Right-Click > New > File
● File name:
─ jdbcQuertDataSource.xsp-config

●
─
─
─
─

●


Connecting to RDBMS
● JDBC xsp-config
●

● Key property
─ complex-extension
– dataInterface
–

●

● If xsp-config file not
immediately recognised as
XML, close and reopen.
─
─


Connecting to RDBMS
● JDBC Query Data Source
Properties
●

● Server
● Port
● Database
●

●

●
─
─
─
─

●

Connecting to RDBMS
● JDBC Query Data Source
Properties
●

● User
● Password
●

● SQL query
●
─
─
─
─

●


Connecting to RDBMS
● Demo 4
─ Create XPage

●

●
─
─
─
─

●


Connecting to RDBMS
● JDBC
●

●
─
─
─
─

●


Connecting to RDBMS
● JDBC
●

●

● Want to build this
●

●
─
─
─
─

●


Connecting to RDBMS
● Create a DataTable
●

●

●

●

●

●

●

●

● Bind using EL
●


Connecting to RDBMS
● DataTable collection is called item
● Computed fields can bind to the data using EL expression
●

●
─
─
─
─

●


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
●

●

●
─

Agenda





●Connecting to RDBMS (Part 2: CRUD)



●Q &A


Connecting to RDBMS(2)
●

●

●

●

●

●

●

●

●

●

● Courtesy of XKCD.com ( http://xkcd.com/327/ )


● 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

The JDBC Data Source Object Model
●
– AbstractDataSource

JDBCConstants
JDBCAbstractDataSource

JDBCUtil

JDBCRecordDataSource
JDBCConcurrencyInfo

AbstractDataContainer JDBCRecordDataContainer JDBCRecord


● Create a New Java Class
─ Select the ls2011 package
─ Right-Click, select
– New > Class

─
─
─
─
─
─

● Use CTRL-F8 to switch
perspectives (if necessary)
●


●

● Package
─ demo.ls2011.jdbc4
─

● Name:
─ JDBCConstants

●


● Constants
─ Not all used in current
implementation
─
─ JDBC Driver properties
─
─ Standard XPages (Domino
oriented URL parameters
─
─ Actions
– New, Open, Edit

●


●

● A class with helpful convenience
methods for working with JDBC,
e.g. open/close connections,
getting column information, setting
types, etc.
●

● Package:
─

● Name:
─ JDBCUtil

●


● Open JDBC Connection
─
─ via Properties object
─
─ via basic properties
– server
– port
– database
– User
– password

●


● Code that actually loads the JDBC
driver
●

●

● Close a connection


● More utility methods
─
─ Get a single
─
─ Get an empty ResultSet to
retirence the ResultSet meta
data to get column information
●


● Utility method to for setting the
appropriate type for the columns when
setting parameters for a JDBC
PreparedStatement
●
─ not all types covered
– Numbers
– Characters

●


●

● Note
─ Use CTRL-Space to get
─ 'hints' on packages and
classes available in the
application package
hierarchy
─

●


●

● Package:
─

● Name:
─ JDBCAbstractDataSource

●

● Modifiers:
─ public abstract
─

● Superclass:
─ com.ibm.xsp.model.Abstract
DataSource
●

● 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
●

●


● 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.
─

●

●

● 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

● 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

● 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)

● More properties
─ keyColumn
– primary key
–
─ tableName
– used for getting
database metadata
–
─ SortOrder
– not implemented.

●

● Optimize – collect metadata
during Connection/Data Source
definition
●

●

● 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


● 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

● State Management for all the
properties
●
─ Handy StateHolderUtil
method for working with List
objects
●

●


● 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.
●

●


●

●


● 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

●

●


● 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
●

●


●

● Name:
─ JDBCRecord

●

● Interfaces
─ com.ibm.xsp.model.
DataObject
– Known interface by the
XPages PropertyResolver,
calls getValue(“<prop>”)
─ java.io.Serializable

●

●


● 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

● 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

●

● Implements the DataObject
methods:
●
─ getType(key)
─ getValue(key)
─ setValue(key,value)
─ isReadOnly()
●


●

● The DataContainer
implementation will callback to
the JDBCRecord before and
after the de/serialized to give
JDBC an opportunity to do
anything it needs
●


● 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
─

●

●


● Next...
●

● Create a concrete class that extends
─
─ JDBCRecordDataContainer
●

● Purpose
─ Manages the life-cycle of the data in a
stateless request response
environment
─ Good place for implementing a caching
strategy
●

●

●

● Package:
─

● Name:
─ JDBCRecordDataContainer
─

● Superclass:
─ com.ibm.xsp.model.Abstract
DataContainer
●

●


● 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
●


●

● 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
●


● 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

● 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()
– ...
–

●

●


● Next...
● create a concrete
implementation that extends
● 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

●

●


●

● Package:
─

● Name
─ JDBCRecordDataSource

●

● Superclass:
─ demo.ls2011.jdbc4.
●


● Required imports
●

● JDBCRecordDataSource
specifies the SQL required for
manipulating the data
●

● MethodBinding
─ Support actions that can be
called before and after
saving row
●

●


● Property setter and getters
●

● Check if the value has been set,
otherwise check for a computed
value
●

●


● More properties...
●

●


● More properties...
●

● recordId is the PK
●

●

●

●

● isReadOnly()
─

● isNewRecord()
─ Depends on the action
– newDocument

●


● 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()


● Save is triggered by the
XspCommandButton
─ save=true
─

● invoke preSave
─ false prevents save

● doSave
● Invoke postSave
●

●

●


● 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.
●


● 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
─


● (C)reate
●

● an 'empty' result set for the
column meta data
●

● returns a JDBCDataContainer
●

●

●

● Concurrency not yet
implemented
●


● (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


● (R)ead........
●

●

●

●

● JDBC code - execute the
select statement


● (D)elete
●

●


● (U)pdate
─ if openDocument
─

● (C)reate
─ if newDocument

●

●

● work with the JDBCRecord
●

●


● SQL INSERT or UPDATE
statement needed?
●

●

● Specify the Prepared
Statement parameters using
the appropriate type of each
column
●

●


● 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
●


● Handle any
SQLExceptions
●

●

●

● OK? return true
●

●


● StateManagement
─ as always!
─
─

● Note the StateHolderUtil
helper mehtods
─ saveMethodBinding()
─ restoreMethodBinding()

●

●


●

● ...... almost there ......
●

●


● Next...
●

● Create an XPages .xsp-config
file that defines the properties
and Domino Designer
integration.
●

●


●
–
com.ibm.xsp.model.group
AbstractDataSource
.DataSource

JDBCAbstractDataSource jdbcAbstractDataSource.xsp-config

JDBCRecordDataSource jdbcRecordDataSource.xsp-config


● Still in the Java Perspective
●

● Under
─ WebContent /
– WEB-INF

●

●


● Create a New File
●

●


● Create a New File
●

● File name:
─ jdbcAbstractDataSource.
xsp-config
●

●


● Define a <group>
─ idenfifed by <group-type>
─

● specify all the properties
declared in
●
─ server
─ port
─ database
─

●

●


● More properties.....
●
─ user
─ password
─ selectString
─ tableName
─

●

●

●


● More properties.....
●
─ keyColumn
─ parameters
– <property-class>
●
ArrayList
– <collection-property>
●
true


● Create .xsp-config for
JDBCRecordDataSource
●

●

●


● <complex-type>
─ specifes an Object with
properties
● <display-name>
─ will be shown in Domino
Designer
● <complex-id>
─ identifier
─

● <complex-class>
─ fully qualified implementing
class
●

●


● More properties....
●

●

●

● <property-class>
─ javax.faces.el.MethodBinding
─

● <property-extension>
─ DominoDesigner directive
─ <method-binding-property>
– true


● <group-type-ref>
─ to include properties from
other .xsp-config definition
files
─

● <complex-extension>
─ <tag-name>
– jdbcRecordDataSource
─ <base-complex-id>
– dataInterface

●

●


● Next.........almost there........honest.....
●

●


● Demo 5
●

● Create a new XPage
●

●

●

●

●

● CTRL-F8


● Create a new XPage
●

● Name:
─ xpDemo5

●


●

●

●


● Should look like this......
●

●


● Data source events can be
added
●
─ Although they show up
in the Data Events tab
─ add them as a property
of the Data Source
●

●


● Simply reference the data
source in SSJS
●

●


● Use EL expressions to bind
EditBoxes to row data columns
●

●


● Save Button
─ Submit
─ Visible only
when row is
editable
●

●


● Navigation
─ result = saved ? XSP_SUCCESS : XSP_FAILURE;

●

●


● Update xpDemo4 to include
command link and command
button to open xpDemo5 with
row details
●

●


● Can use the Document
Simple Actions
─ no programming!

●

●


● Will add the request parameters
─ action=openDocument&documentId=<item.empno>

●

●


● Click New to open xpDemo5
●

●


● Open, ReadOnly, Edit, QuerySave Event, Edit, Save
●

●


Agenda








●Q &A


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
●

●
─

Agenda








●Q &A


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
─
─
─
─

●


Agenda








●Q &A


Q&A for General XPages Development
●

●

●

●

●

●

●

●

●

●

● blog.sequill.com
─ connect to development, general Xpages developemnt
●


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

Q&A
●We ask you answer!


My Question:

Do you want MORE?


My Answer:

bleedyellow.com


Q&A
●Now it is your turn!


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.


● Objectives for todays session
─
reads a CSV file from the
local filesystem
─
─
─
─
reads data from an RDBMS
by executing SQL via JDBC
–

●

●
─
─
─
─

●

● 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.
─

●

SHOW107: The DataSource Session: Take XPages data boldly where no XPages data has been taken before

SHOW107: The DataSource Session: Take XPages data boldly where no XPages data has been taken before

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Viewers also liked

Viewers also liked (20)

Similar to SHOW107: The DataSource Session: Take XPages data boldly where no XPages data has been taken before

Similar to SHOW107: The DataSource Session: Take XPages data boldly where no XPages data has been taken before (20)

More from Stephan H. Wissel

More from Stephan H. Wissel (9)

SHOW107: The DataSource Session: Take XPages data boldly where no XPages data has been taken before