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 IrelandStephan H. Wissel | LTPA | IBM Singapore

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

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

─ Write a data source that 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─

AbstractDataSource AbstractDataContainer

ComponentBindingObject ValueBindingObject

DataPublishingObject

StateHolder

DataSource

DataContainer

Externalizable

● 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

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

● 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

● 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

● 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

● Data Container─

● Data is a List of CSVRowObjects

● Data Container

● Externalizable─

● Data Container

● The actual implementation to get the data

● 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

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:\Domino\jvm\lib\security\java.policy

● Choices:

─ Store JARs under C:\Domino\xsp\shared– 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─

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 AbstractDataContainer

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

● JDBC code using ResultSet─

─ Could consider RowSets and have it handle disconnected mode

Connecting to RDBMS

● JDBC Data Container─ 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

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

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

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

● User

● Password

● SQL query

Connecting to RDBMS

● Demo 4─ Create XPage

Connecting to RDBMS

● JDBC

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

JDBCUtil

JDBCConcurrencyInfo

JDBCRecord

JDBCAbstractDataSource

JDBCRecordDataSource

JDBCRecordDataContainer

JDBCConstants

JDBCUtil

JDBCConcurrencyInfo

JDBCRecord

JDBCConstants

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

– New > Class ─

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

● Create a New Java Class

● 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

JDBCUtil

JDBCConcurrencyInfo

JDBCRecord

JDBCConstants

● 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

● 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

JDBCUtil

JDBCConcurrencyInfo

JDBCRecord

JDBCConstants

● Note─ Use CTRL-Space to get─ 'hints' on packages and

classes available in the application package hierarchy

● 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

● 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

● 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

JDBCUtil

JDBCConcurrencyInfo

JDBCRecord

JDBCConstants

● 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

JDBCUtil

JDBCConcurrencyInfo

JDBCRecord

JDBCConstants

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

JDBCUtil

JDBCConcurrencyInfo

JDBCRecord

JDBCConstants

● 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

● Name:─ JDBCRecordDataContainer─

DataContainer

● com.ibm.xsp.model.AbstractDataContainer

─ 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

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

JDBCUtil

JDBCConcurrencyInfo

JDBCRecord

JDBCConstants

● 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

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

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

AbstractDataSource

com.ibm.xsp.model.group.DataSource

jdbcAbstractDataSource.xsp-config

jdbcRecordDataSource.xsp-config

● Still in the Java Perspective

● Under─ WebContent /

– WEB-INF

● Create a New File

● File name:─ jdbcAbstractDataSource.

xsp-config

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

● specify all the properties declared in JDBCAbstractDataSource

─ server─ port─ database─

● More properties.....

─ user─ password─ selectString─ tableName─

─ 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

● 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

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

●We ask you answer!

My Question:

Do you want MORE?

My Answer:

bleedyellow.com

●Now it is your turn!

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.

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

Jim Quill | XPages Developer | IBM IrelandStephan H. Wissel | LTPA | IBM Singapore

Agenda

●Simple CSV file Data Source

●Q & A

● 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

─ Write a data source that reads data from an RDBMS by executing SQL via JDBC

Agenda

●Q & A

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

AbstractDataSource AbstractDataContainer

ComponentBindingObject ValueBindingObject

DataPublishingObject

StateHolder

DataSource

DataContainer

Externalizable

● 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

Agenda

●Simple CSV File Data Source

●Q & A

● 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

● 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

● 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

● 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

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

● Select Finish

● Data is a List of CSVRowObjects

● Data Container

● Externalizable─

● Data Container

● The actual implementation to get the data

● 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

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:\Domino\jvm\lib\security\java.policy

● Choices:

─ Store JARs under C:\Domino\xsp\shared– 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─

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

● Create a new class

● Extend AbstractDataContainer

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

● JDBC Data Container─ 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

● 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

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

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

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

● Server

● Port

● Database

Connecting to RDBMS

● User

● Password

● SQL query

Connecting to RDBMS

● Demo 4─ Create XPage

Connecting to RDBMS

● JDBC

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

● 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

JDBCUtil

JDBCConcurrencyInfo

JDBCRecord

JDBCConstants

JDBCUtil

JDBCConcurrencyInfo

JDBCRecord

JDBCConstants

● 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

JDBCUtil

JDBCConcurrencyInfo

JDBCRecord

JDBCConstants

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

● 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

JDBCUtil

JDBCConcurrencyInfo

JDBCRecord

JDBCConstants

● Note─ Use CTRL-Space to get─ 'hints' on packages and

classes available in the application package hierarchy

● Name:─ JDBCAbstractDataSource

● Modifiers:─ public 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

● 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

● 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

JDBCUtil

JDBCConcurrencyInfo

JDBCRecord

JDBCConstants

● 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

JDBCUtil

JDBCConcurrencyInfo

JDBCRecord

JDBCConstants

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

JDBCUtil

JDBCConcurrencyInfo

JDBCRecord

JDBCConstants

● 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

● Name:─ JDBCRecordDataContainer─

DataContainer

● com.ibm.xsp.model.AbstractDataContainer

─ 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

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

JDBCUtil

JDBCConcurrencyInfo

JDBCRecord

JDBCConstants

● 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

● 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

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

AbstractDataSource

com.ibm.xsp.model.group.DataSource

jdbcAbstractDataSource.xsp-config

jdbcRecordDataSource.xsp-config

● Still in the Java Perspective

● Under─ WebContent /

– WEB-INF

● File name:─ jdbcAbstractDataSource.

xsp-config

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

● specify all the properties declared in JDBCAbstractDataSource

─ server─ port─ database─

─ user─ password─ selectString─ tableName─

─ 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

● 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

● CTRL-F8

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

●We ask you answer!

My Question:

Do you want MORE?

My Answer:

bleedyellow.com

●Now it is your turn!

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.

show107: the datasource session: take xpages data boldly where no xpages data has been taken before

data sourceq

data souce

data objectives

data demo

data sourcesession

custom data sources

data life cycle

ibm corporation

Documents

wakanda datasource api

xpages & dojo

xpages extension library - entwicklercamp · the xpages...

jumpbook herbalife datasource windows app

xpages business applications

solr as a sparksql datasource

grafana datasource plugin

standard datasource enhancement

workflow for xpages

ddive11 - xpages

xpages - the basics

ec13 xpages-basic

xpages guru webinar - xpages sample apps

splunk pci 2.0 datasource

caqh universal provider datasource

sap bw datasource

xpages mobile controls

graphdb in xpages

email as a datasource

hibernate in xpages