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

1. SHOW107 The Data Source Session: Take XPages data boldly where no XPages data has been taken before Jim Quill | XPages Developer | IBM Ireland Stephan H. Wissel | LTPA | IBM Singapore © 2011 IBM Corporation

2. Agenda ●Overview – options to connect to data ●The Data Source object model ●Setting up your development environment ●Simple CSV file Data Source ●Debugging your code ●Connecting to RDBMS ●Connecting to Non relational data sources ●Deploying your data source ●Q &A © 2011 IBM Corporation 2

3. Overview – options to connect to data ● Built-in DataSources ─ Domino® View ─ Domino® Document ─ ● SeverSide JavaScript ─ Write custom Java™ code to connect any data source and return that data as an object, array, List, ResultSet, or DataModel will enable XPages controls to consume that data. ─ ● Any control that holds data, for display or editing can be bound to an item of data, a field in a Domino document or a property of a Managed Bean, for example. ● ● Container controls, i.e. DataTable, Repeat, and View Panel can be bound to a single item or a collection of items and will iterate over the data – © 2011 IBM Corporation

5. Overview – options to connect to data ● Built-in DataSources Benefits ─ ─ declaratively add and reuse custom data sources to an XPage, ─ ─ computed properties ─ ─ easy access the data souce in SSJS ─ ─ nest DataSources so contents of one data source can be bound to computed properties of another data source defined on an inner panel that is in a Repeat control ─ ─ control behavoiur via URL parameters ─ ─ add your own query/postSaveEvents, and more © 2011 IBM Corporation

6. Overview – options to connect to data ● Objectives for todays session ─ ─ Write a data source that reads a CSV file from the local filesystem ─ ─ ─ ─ ─ Write a data source that reads data from an RDBMS by executing SQL via JDBC – ● ● ─ © 2011 IBM Corporation

7. Agenda ●Overview – options to connect to data ●The Data Source object model ●Setting up your development environment ●The first data source ●Debugging your code ●Connecting to RDBMS ●Connecting to Non relational data sources ●Deploying your data source ●Q &A © 2011 IBM Corporation 7

8. The Data Source Object Model ● For the two core storage artifacts, View and Documents, XPages provides a convenient mechanism to declaratively add these two data sources to your application without any coding ─ All properties can be computed using JavaScript or an EL expression ─ Tight integration with a set of easy to use Simple Actions for working with Documents and View ─ Ability to specify request parameters to control and influence the behavior of the data source ● ● Within the XPages framework, data sources are based on two key classes ─ com.ibm.xsp.model.AbstractDataSource ─ com.ibm.xsp.model.AbstractDataContainer ─ – © 2011 IBM Corporation

9. The Data Source Object Model ● ─ ComponentBindingObject ValueBindingObject – DataPublishingObject Externalizable StateHolder DataContainer DataSource AbstractDataSource AbstractDataContainer © 2011 IBM Corporation

10. The Data Source Object Model ● AbstractDataSource Responsibilities ─ Data source id management – BeanId – UniqueId ─ RuntimeProperty management – Computed properties can be saved as runtime property so its values doesn't have to be repeatedly calculated ─ State Management – Base properties var, scope, ignoreRequestParams, requestParamPrefix – Property accessors for state of component to be recreated ─ Data Container Management ─ DataPublishing – pushData, popData – publishes the DataModel to request scope using the specified var attribute as the key ● © 2011 IBM Corporation

11. The Data Source Object Model ● Data Container Responsibilities ─ Externalizable support ─ Manages the life cycle of the data – if it doesn't continuously store the data between requests, it knows how to retrieve it. ─ ─ ● © 2011 IBM Corporation

13. Setting up your development environment ● What you need ─ IBM® Lotus Domino® Designer 8.5.2 ─ IBM® Lotus Domino® 8.5.2 ─ IBM® DB2® ─ ─ ● What you should have to hand: ─ Javadoc – XPages Extensibility API Documentation – http://www-10.lotus.com/ldd/ddwiki.nsf/dx/XPages_Extensibility_API_Document ation ─ ─ Wiki – XPages Extensibility API Developers Guide – http://www-10.lotus.com/ldd/ddwiki.nsf/dx/Master_Table_of_Contents_for_XPag es_Extensibility_APIs_Developer_Guide ● © 2011 IBM Corporation

14. Agenda ●Overview – options to connect to data ●The Data Source object model ●Setting up your development environment ●Simple CSV File Data Source ●Debugging your code ●Connecting to RDBMS ●Connecting to Non relational data sources ●Deploying your data source ●Q &A © 2011 IBM Corporation 14

16. Simple CSV Data Source ● Overview ─ Create a New Application ─ Project setup ─ Extend AbstractDataSource – Manages the DataSource properties ─ Extend AbstractDataContainer – Manages the Data life cycle, caching, refreshing ─ Create an xsp-config file that describes the DataSource so it can integrate with Lotus Domino® Designer and the Xpages Framework ● ● © 2011 IBM Corporation

17. Simple CSV Data Source ● Application Setup ─ Grant Anonymous Manager access level File > Application > Access Control... ─ Specify oneuiv2 as the Web theme. File > Application > Properties > Xpages ─ CTRL-S to save changes © 2011 IBM Corporation

18. Simple CSV Data Source ● Switch to the Java™ perspective ─ Window > Open Perspective > Java ● ● Shortcut ─ CTRL-F8 ● ● ● A virtual file system for the NSF ─ organized like a WAR © 2011 IBM Corporation

19. Simple CSV Data Source ● Create a new Source Folder ─ Select the application NSF (ls2011.nsf) ─ Right-Click > New > Source Folder ─ ● Do not use Local as the source folder ─ Java files stored here are actually located on the local workstation file system in the IBM® Lotus Domino® Designer workspace and are not inside the NSF file. ─ When XPages are compiled to Java classes, the intermediate Java source file is written to here. – Can be useful to examine these source files to © 2011 IBM Corporation

21. Simple CSV Data Source ● Appropriate Java Build Path is automatically configured ● ● Select src folder ─ Right-Click > Build Path > Configure Build Path... ─ Select Libraries tab ● © 2011 IBM Corporation

22. Simple CSV Data Source ● Verify the src folder will generate the class files into the expected location (ls2011.nsf/WebContent/ WEB-INF/classes) ● Select src folder ─ Right-Click > Build Path > Configure Output Folder... ─ ● Note: To see the classes folder use the Navigator view ─ Menu > Window > Show Eclipse Views > Navigator © 2011 IBM Corporation

24. Simple CSV Data Source ● Enter the New Java Class details ─ ─ Package: – demo.ls2011.csv ─ ─ Name: – CSVDataSource ─ ─ Superclass: – com.ibm.xsp.model.AbstractDataSource ─ ─ Interfaces: – com.ibm.xsp.model.DataSource ─ ─ Leave inherit abstract methods checked. ● Select Finish © 2011 IBM Corporation

25. Simple CSV Data Source ● The CSV File Data Source has 4 properties ─ ─ csvFilePath – location on the local file system ─ separator – field delimiter – ─ firstLineIsHeader – treat the first line of the CSV file as column headers. – ─ trimWhiteSpace – Postprocessing the data, could be anything you like © 2011 IBM Corporation

26. Simple CSV Data Source ● Theory: Literal values compared to Computed values ─ ─ Property setter called for Literal values – getter will simply return the set value – – ─ SetValueBinding called for Computed values – Getter has to evaluate the corresponding value expression to – AbstractDataSource.RuntimeProperties help optimize reading these values ● © 2011 IBM Corporation

28. Simple CSV Data Source ● Java Bean property accessors ─ Always follow this general structure – If set directly, return the value – Otherwise check for a computed value ● Specifies the location of the target CSV file © 2011 IBM Corporation

32. Simple CSV Data Source ● UniqueId ─ Using a combination of the Data Source properties, than can be repeatedly calculated, construct an id to identity the data souce, such that any property changes that would effect the data would generate a new id. ● Bean Id ─ The key used to store the DataContainer for the DataSource ─ AbstractDataSource calculates beanId, DataSource developer specified how to compose the uniqueId ─ Default scope for DataSources is View Scope ─ If data shared – scope = session – scope = application ─ Then beanId = uniqueId © 2011 IBM Corporation

34. Simple CSV Data Source ● Support changing functionality via request parameters ● http://server/app.nsf/csv.xsp?separator=:&firstLineIsHeader=false ─ ● ● PrefixRequestParam ─ Enable request parameters to be specified for individual data sources ─ ● ● Save is called by XPages Framework if Submit event was triggered © 2011 IBM Corporation

35. Simple CSV Data Source ● State Management ● StateHolder is a JSF interface that must be implemented by components that need to save their state between requests ● Saving and restoring is done as a Serializable object ─ Must have a public no-args constructor ─ ● Component tree is built for the initial request, and then restoring for subsequent postbacks ● If it is not done right, components behave differently and data disappears in subsequent POST requests after the initial GET ─ ● © 2011 IBM Corporation

37. Simple CSV Data Source ● CSVRowData ─ Represents a row of data ● ● Implement DataObject ─ XPages Property Resolver knows about this type ─ For EL expression like item.name instead of calling getName() as is typical for Java Beans the Property Resolver will call getValue(“name”) ● ─ Is also implemented for DominoDocument ─ Similar to ViewRowData Interface used for row data items in a Domino View. ─ Documentation Bug – Interface com.ibm.xsp.model.DataObject is not published. © 2011 IBM Corporation ─

38. Simple CSV Data Source ● CSVRowData ─ Create a new Java Class ─ ─ Package – demo.ls2011.scv – ─ Name – CSVRowData ─ ─ Interfaces – com.ibm.xsp.model. DataObject – java.io.Serializable ● © 2011 IBM Corporation

40. Simple CSV Data Source ● Data Object ● ● ● ● ● ● ● GetValue() ─ #{item.name} – gets the value for the field labeled “name” – ─ #{item[2]} – gets the value for the second field – useful if CSV file doesn't use the first row to specify column names © 2011 IBM Corporation –

42. Simple CSV Data Source ● In the Package Navigator, Select the src folder, Right-Click > New > Class to create a New Java Class for the Data Container ● ─ Package – demo.ls2011.csv – ─ Name: – CSVDataContainer – ─ Superclass: – com.ibm.xsp.model. AbstractDataContainer ● ● Select Finish © 2011 IBM Corporation

50. Simple CSV Data Source ● Complex Types in the xsp-config file ─ ─ Used to specify non-primative types in Xpages – Objects ─ Represented using their own tags ─ Can specify a Class or Interface ● ─ ● © 2011 IBM Corporation

51. Simple CSV Data Source ● xsp-config ● ● Declare the namespace ● Descriptive information that wil be used by Domino® Designer ● The class the implements the functionality and property support ● Group-type-ref ─ Base data source properties ─ ● © 2011 IBM Corporation

55. Simple CSV Data Source ● Demo 2 ● ● Switch to the Domino Designer perspective ─ CTRL-F8 > Domino Designer ● Create a new Xpage called xpDemo1 ─ XPages > New Xpage... ─ Name is xpDemo1 ─ Select on the blank XPage design canvas so the XPage design Properties tab appears ● In the XPage Properties tab ─ Open the Data section ─ Click Add and you will see CSV Data Source in the drop down list ─ ● © 2011 IBM Corporation

63. Simple CSV Data Source ● Demo 3 ● ● Button performs partial refresh on outer Panel when clicked. ─ ─ Useful for testing data source State Management ─ ─ If is is wrong, data will disappear after completion of the POST request © 2011 IBM Corporation

66. Debugging you code ● Enable Java debugging on IBM® Lotus Domino® by adding the following lines to notes.ini ─ ─ ─ ─ ─ ─ JavaEnableDebug=1 ─ JavaDebugOptions=transport=dt_socket,server=y,suspend=n,address=8 000 ● ● ─ ● © 2011 IBM Corporation

67. Debugging you code ● Restart IBM® Lotus Domino® and verify that debugging has been enabled by checking the server console for the following message: – > Listening for transport dt_socket at address: 8000 – 1/01/2011 17:08:45 JVM: Java Virtual Machine initialized. – 1/01/2011 17:08:45 HTTP Server: Java Virtual Machine loaded ─ ─ ─ ─ ● © 2011 IBM Corporation

68. Debugging you code ● Instead of switching perspectives, stay in the Domino Designer perspective and open the Navigator and Package Explorer views. ─ Window > Show Eclipse Views > Other... ─ Select Navigator (under General) ─ Click OK ─ ─ ─ ─ ● © 2011 IBM Corporation

69. Debugging you code ● The Navigator opens be default beside the Control palette and the Data palette ● ● One benefit of the Navigator over the Package Explorer is that the Navigator show then compiled Java classes for the application ● ● However it does not have the Right-Click context menus for configuring the Java build path ─ ─ ─ ─ © 2011 IBM Corporation

71. Debugging you code ● In Package Explorer, double-click on the class you are interested in debugging to open it. ● Set a breakpoint in your code by double-clicking on the line number for the method you want to debug. ● Notice a small circle icon will appear beside the line. ─ ─ ─ ─ ● © 2011 IBM Corporation

80. Connecting to RDBMS ● Create a read only Data Source that allows a developer to declaratively specify JDBC connection information and an SQL query that retrieves the appropriate data ─ ─ ─ ● © 2011 IBM Corporation

81. Connecting to RDBMS ● Install DB2® ─ Include the sample databases ─ Assumes user is db2admin with password as password ─ ● Locate the JDBC Type 4 driver ─ db2jcc.jar ─ db2jcc_license.jar ─ will need them later ─ ─ ─ ─ ● © 2011 IBM Corporation

89. Connecting to RDBMS ● In the Java perspective, open the Navigator ● Expand the WebContent/WEB-INF folder ● ● Notice there is no lib folder ● ● Select WEB-INF ● Right-Click > New > Folder ─ ─ ─ ─ ● © 2011 IBM Corporation

95. Connecting to RDBMS ● Check the logs ● ● ● Security Exception ─ checkPropertiesAccess() is not managed by AgentSecurityManager ─ Doesn't check if unrestriced users can perform the operation ─ ─ ─ ─ ─ ● Need to move JDBC drivers to trusted location (since call is wrapped by AccessController.doPrivileged() ) ● © 2011 IBM Corporation

96. Connecting to RDBMS ● C:Dominojvmlibsecurityjava.policy ● ● ● ● Choices: ● ─ Store JARs under C:Dominoxspshared – it is a trusted location – XPages ClassLoader will search for JARs here when runtime starts ─ ─ Trust the specific NSF application as a location ● © 2011 IBM Corporation

100. Connecting to RDBMS ● ComposeUniqueId() ─ Based on data source properties ─ ● getDataObject() ─ return the data ● ● isReadOnly() ● ● ReadRequestParams() ─ data source specific options ● ● load() ─ Called by the XPages framework ● Save() ─ Called by the XPages framework © 2011 IBM Corporation

107. Connecting to RDBMS ● Override abstract methods ● ● Connection information and SQL query. ─ Changing the sort order, which still reads the data from the same data source could change the UniqueId, triggering the DataContainer to refresh any cached data ● ● getDataObject gets the data from the DataContainer ─ ─ © 2011 IBM Corporation ─

111. Connecting to RDBMS ● JDBC Data Container ● ● DataContainers are not stored with the DataSource in the view ● The are managed by a scope Bean Manager and are identified by their beanId ─ ─ ─ ─ ● © 2011 IBM Corporation

112. Connecting to RDBMS ● JDBC Data Container ● ● Get the data ● ● Other stragegy is to get the data as part of the DataSource and just have container manage its lifecycle ─ Can it be cached ─ Does it need to be refereshed ─ Resource pooling ─ ─ ─ ─ © 2011 IBM Corporation ●

114. Connecting to RDBMS ● JDBC Data Container ─ Leverage FacesContextListener to manage the lifecycle of the data and caching stratagies – beforeRenderingPhase() – beforeContextReleased() ─ ─ ─ ─ ● © 2011 IBM Corporation

115. Connecting to RDBMS ● JDBC Data Container ─ ─ Implements Externalizable ─ ─ Class handles serialization of each property itself ─ ─ Optimization to avoid the serialization code having to intropsect and figure out all the datatypes. ─ ─ ● © 2011 IBM Corporation

116. Connecting to RDBMS ● Create ResultSetModelEx ● ─ Extends TabularDataModel – better integration with XPages Pager control for ResultSets ─ ─ Delegates to ResultSetDataModel ─ ─ ─ ● © 2011 IBM Corporation

117. Connecting to RDBMS ● ResultSetModelEx ● ● Some properties and constructors ● ● Wraps a ResultSetDataModel to which it delegates most methods, except getRowCount() as we don't want to return the standard -1 (prevents us working with the pager controls. DataModels that have an unknown count can extend TabularDataModel ─ ─ ─ © 2011 IBM Corporation

118. Connecting to RDBMS ● ResultSetModelEx ● ● Pager estimates number rows and ask data model if it knows if rowCount is bigger than current maxCount ● ● For the current page, always return the current page range + 1 – causes the Pager to indicate that there are more rows ─ ─ ─ ─ © 2011 IBM Corporation

120. Connecting to RDBMS ● ResultSetModelEx ─ ─ If isRowAvailable returns false from the delegated ResultSetDataModel then we know we have found a potential value for the actual row count ─ HasMoreRows() will start using this value and since it will be less than the current deduced max in the pager, it will readjust based on this value. ─ © 2011 IBM Corporation

131. Connecting to RDBMS ● Pager tries to deduce last page ● ...Next indicates more pages ● ● Keeps increasing until no row is found, then Pages adjusts last page ● Next indicates a max count found ● ● ● ─ ─ © 2011 IBM Corporation

132. Agenda ●Overview – options to connect to data ●The Data Source object model ●Setting up your development environment ●The first data source ●Debugging your code ●Connecting to RDBMS (Part 2: CRUD) ●Connecting to Non relational data sources ●Deploying your data source ●Q &A © 2011 IBM Corporation 132

134. Connecting to RDBMS(2) ● Create a JDBC Data Source that supports working with individual rows in a table. Should support operations such as: ─ ─ (C) inserting a new row ─ (R) selecting a specific row ─ (U) updating an existing row ─ (D) deleting a row ─ ─ ● Like a DominoView -> DominoDocument, Master -> Detail type relationship ● ─ JDBCQueryDataSource – works with several rows – ─ JDBCRecordDataSource – works with a single row © 2011 IBM Corporation

135. The JDBC Data Source Object Model ● – AbstractDataSource JDBCConstants JDBCAbstractDataSource JDBCUtil JDBCRecordDataSource JDBCConcurrencyInfo AbstractDataContainer JDBCRecordDataContainer JDBCRecord © 2011 IBM Corporation

137. Connecting to RDBMS(2) ● Create a New Java Class ─ Select the ls2011 package ─ Right-Click, select – New > Class ─ ─ ─ ─ ─ ─ ● Use CTRL-F8 to switch perspectives (if necessary) ● © 2011 IBM Corporation

139. Connecting to RDBMS(2) ● Constants ─ Not all used in current implementation ─ ─ JDBC Driver properties ─ ─ Standard XPages (Domino oriented URL parameters ─ ─ Actions – New, Open, Edit ● © 2011 IBM Corporation

141. Connecting to RDBMS(2) ● Create a New Java Class ● ● A class with helpful convenience methods for working with JDBC, e.g. open/close connections, getting column information, setting types, etc. ● ● Package: ─ demo.ls2011.jdbc4 ─ ● Name: ─ JDBCUtil ● © 2011 IBM Corporation

145. Connecting to RDBMS(2) ● Utility method to for setting the appropriate type for the columns when setting parameters for a JDBC PreparedStatement ● ─ not all types covered – Numbers – Characters ● © 2011 IBM Corporation

148. Connecting to RDBMS(2) ● Create a New Java Class ● ● Package: ─ demo.ls2011.jdbc4 ─ ● Name: ─ JDBCAbstractDataSource ● ● Modifiers: ─ public abstract ─ ● Superclass: ─ com.ibm.xsp.model.Abstract DataSource ● © 2011 IBM Corporation

149. Connecting to RDBMS(2) ● Imports that can be added as the abstract data source class is developed ● ● Has the abstract modifier ● ● This class will be extended later on with a concrete class that will implement the row oriented specifics of the data source ● ● © 2011 IBM Corporation

150. Connecting to RDBMS(2) ● Specify member variables that represent properties for the JDBC-based data source ─ server ─ port ─ database, etc ─ ● parameters is as List ─ used to store name-value (com.ibm.xsp.Paramster) pairs that can be used to pass information to the data source. ─ ● ● © 2011 IBM Corporation

151. Connecting to RDBMS(2) ● Create property accessor methods ─ server ─ port ─ ● Follow the standard 'template' for getters ─ 1) check if instance variable is set ─ 2) check for a corresponding value binding (if value can be computed) ─ 3) retrun null or default for primitive (int etc.) types ● ● action ─ 'read only' property ─ set via request parameter – action=newDocument © 2011 IBM Corporation

152. Connecting to RDBMS(2) ● More property accessors ─ database ─ user ● If RuntimeProperties is implmemented, get it here. ● ● Extend the standard 'template' for getters ─ 1) if using RuntimeProperties, get it from there ─ 2) check if instance member variable is set ─ 3) check for a corresponding value binding (if the value can be computed) ─ 4) retrun null or default for primitive (int etc.) types © 2011 IBM Corporation

153. Connecting to RDBMS(2) ● More properties ─ password ─ selectString ● ● selectString ─ idea was that whether one row is indented to be returned (JDBCRecordDataSource), or several (JDBCQueryDataSource). ─ oth have a SQL select statement in common, so property is in abstract class – then decided to modify/override with concurrency column info (not fully implemented) ● © 2011 IBM Corporation

154. Connecting to RDBMS(2) ● More properties ─ keyColumn – primary key – ─ tableName – used for getting database metadata – ─ SortOrder – not implemented. ● ● Optimize – collect metadata during Connection/Data Source definition ● © 2011 IBM Corporation

155. Connecting to RDBMS(2) ● ● UniqueId ─ An identifier that distinguishes this JDBC data source from other JDBC data sources – can be repeatedly re-constructed form the data source properties ─ ─ used as the name for storing data in scope (if shared) ─ ─ connection information + request parameter info + select statement © 2011 IBM Corporation

156. Connecting to RDBMS(2) ● Read general request parameters ─ action ─ sortOrder ● ● Abstract methods sub-classes must implement ─ isReadOnly() ─ getDataObject() ─ load() ─ save() ● ● Helper methods for connection URL and opening the JDBC connection © 2011 IBM Corporation

159. Connecting to RDBMS(2) ● Next... ● ● create a helper class JDBCConcurrencyInfo ● ─ Not really used. Keep in mind that it (or this feature) will be required for taking this sample further for production use. ● ● © 2011 IBM Corporation

161. Connecting to RDBMS(2) ● Concurrency ─ Pessimistic – RDBMS specific ─ ─ Optimistic – which column provides the 'timestamp' that can be compared for row updates – ─ Force – Last Writer Wins – Not really a good idea ● ● © 2011 IBM Corporation

163. Connecting to RDBMS(2) ● Next... ● ● Create a concrete class that implements DataObject ─ ─ JDBCRecord ● ● Purpose ─ Enables the data that are returned to be simply referenced with an EL expression using the data field/column name ● ● © 2011 IBM Corporation

164. Connecting to RDBMS(2) ● Create a New Java Class ● ● Name: ─ JDBCRecord ● ● Interfaces ─ com.ibm.xsp.model. DataObject – Known interface by the XPages PropertyResolver, calls getValue(“<prop>”) ─ java.io.Serializable ● ● © 2011 IBM Corporation

165. Connecting to RDBMS(2) ● When the XPages Framework calls ─ DataSource.getDataObject() ─ which in turn calls ─ DataContainer.getRecord() ● This is the returned object ● Is essentially the BackingBean for the part of the UI that displays the data from the Data Source ● ● wrappedData ─ JDBC ResultSet ─ transient - not serializable need to be managed ● © 2011 IBM Corporation

166. Connecting to RDBMS(2) ● Constructor ─ ResultSet – wrapped ─ UniqueId – Primary Key Column for the record ─ Should be a List<String> ─ ● Get the Column Types for each of the Columns based on the ResultSet meta data ● ● selectSQL ─ used to recreate the ResultSet as necessary ● © 2011 IBM Corporation

168. Connecting to RDBMS(2) ● ● The DataContainer implementation will callback to the JDBCRecord before and after the de/serialized to give JDBC an opportunity to do anything it needs ● © 2011 IBM Corporation

169. Connecting to RDBMS(2) ● discardWrappedObject ─ ResultSet is closed before serialization. ─ ─ ● Several other methods not yet fully implemented that will be useful in the future: ─ CheckRecordValidity() – row may been deleted between requests ─ ● ● © 2011 IBM Corporation

171. Connecting to RDBMS(2) ● Next... ● ● Create a concrete class that extends AbstractDataContainer ─ ─ JDBCRecordDataContainer ● ● Purpose ─ Manages the life-cycle of the data in a stateless request response environment ─ Good place for implementing a caching strategy ● ● © 2011 IBM Corporation

172. Connecting to RDBMS(2) ● Create a New Java Class ● ● Package: ─ demo.ls2011.jdbc4 ─ ● Name: ─ JDBCRecordDataContainer ─ ● Superclass: ─ com.ibm.xsp.model.Abstract DataContainer ● ● © 2011 IBM Corporation

173. Connecting to RDBMS(2) ● com.ibm.xsp.model.Abstract DataContainer ● ─ contains some basic support for making the data source Externalizable ● ● Need to implement the required serialize and deserialize methods ● © 2011 IBM Corporation

174. Connecting to RDBMS(2) ● ● JDBCRecord ─ the data object ● ● FaceContectListener ─ used to discard resources at the end of the request ● ● In this implementation the DataSource creates the JDBCRecord and passes it into the Constructor ● © 2011 IBM Corporation

175. Connecting to RDBMS(2) ● FacesContextListener ─ Can use this listener to manage the data through the various phases of the JSF Lifecycle ─ ● ● ● getRecord() ● ● Called from DataSource.getDataObject() – Xpages Framework entry point for Data Source data © 2011 IBM Corporation

176. Connecting to RDBMS(2) ● Externalizable ● ─ For Serialization when the data to be serialized is complex – since the datatype are known can use the API to specify the type avoid the introspection – readBoolean() – readChar() – readObject() – ... – ● ● © 2011 IBM Corporation

178. Connecting to RDBMS(2) ● Next... ● create a concrete implementation that extends JDBCAbstractDataSource ● that will work with a single row of data in a table ● ● It will support operations to ─ (C)reate -> Insert ─ (R)ead -> Select ─ (U)pdate -> Update ─ (D)elete-> Delete ● ● © 2011 IBM Corporation

179. Connecting to RDBMS(2) ● Create a New Java Class ● ● Package: ─ demo.ls2011.jdbc4 ─ ● Name ─ JDBCRecordDataSource ● ● Superclass: ─ demo.ls2011.jdbc4. JDBCAbstractDataSource ● © 2011 IBM Corporation

180. Connecting to RDBMS(2) ● Required imports ● ● JDBCRecordDataSource specifies the SQL required for manipulating the data ● ● MethodBinding ─ Support actions that can be called before and after saving row ● ● © 2011 IBM Corporation

184. Connecting to RDBMS(2) ● If no action is specified, assumes newDocument ● ● Whenever the XPages component tree is being constructed or traversed any data controls are 'published' ● ● DataPublisher() calls getDataObject() ● getDataContainer() is implemented in AbstractDataSource ─ checks uniqueId() ─ calls load() ● © 2011 IBM Corporation

186. Connecting to RDBMS(2) ● Invoke the Data Source Action ─ push() ─ invoke() ─ pop() ● ● If it's a new document, then beforehand, for example, queryNewDocument, there is no record/document, so no data to push to request scope, so in this case, record would be null. ● © 2011 IBM Corporation

187. Connecting to RDBMS(2) ● Read JDBCRecordDataSource specific request parameters ● ● JDBCConstants ─ URL_PARAM_ID – documentId ● ● DataSource will be published using the var attribute ─ record1 ● Can publish the data using several identifiers, ─ currentDocument ─ © 2011 IBM Corporation

189. Connecting to RDBMS(2) ● (R)ead ● ● JDBC PreparedStatement ● ● If documentId not set in URL, or ignoring request parameters for this data source look into the supplied Parameters ● ● ● If asked to read a row, but no PK specified, default to Create/Insert a new row © 2011 IBM Corporation

194. Connecting to RDBMS(2) ● For UPDATE, the PK value should be specified in the WHERE clause ● ● ● ● executeUpdate() ─ should update/insert 1 row ● ● ● If it was INSERT – get the PK value so it can be stored in the JDBCRecord ● ● © 2011 IBM Corporation

199. Connecting to RDBMS(2) ● – com.ibm.xsp.model.group AbstractDataSource .DataSource JDBCAbstractDataSource jdbcAbstractDataSource.xsp-config JDBCRecordDataSource jdbcRecordDataSource.xsp-config © 2011 IBM Corporation

207. Connecting to RDBMS(2) ● <complex-type> ─ specifes an Object with properties ● <display-name> ─ will be shown in Domino Designer ● <complex-id> ─ identifier ─ ● <complex-class> ─ fully qualified implementing class ● ● © 2011 IBM Corporation

208. Connecting to RDBMS(2) ● More properties.... ● ● ● ● <property-class> ─ javax.faces.el.MethodBinding ─ ● <property-extension> ─ DominoDesigner directive ─ <method-binding-property> – true © 2011 IBM Corporation

209. Connecting to RDBMS(2) ● <group-type-ref> ─ to include properties from other .xsp-config definition files ─ ● <complex-extension> ─ <tag-name> – jdbcRecordDataSource ─ <base-complex-id> – dataInterface ● ● © 2011 IBM Corporation

229. Connecting to non relational data sources ● XML ● Web Services (REST/SOAP) ● etc ● ● Same approach as two previous examples ● ● Extend AbstractDataSource to define what properties the data source has ● ● Extend AbstractDataContainer to manage the life-cycle of the data in the context of a disconnected web application where the data is only live for the duration of the request ● ● © 2011 IBM Corporation ─

231. Deploying your data source ● To create a sharable library (OSGi Plugin), see ─ ─ http://www-10.lotus.com/ldd/ddwiki.nsf/dx/Creating_an_XPag es_Library ● ● For deployment on Lotus Domino® and Lotus Notes® Client, see ─ ─ http://www-10.lotus.com/ldd/ddwiki.nsf/dx/Deploying_XPage_ Libraries ─ ─ ─ ─ ● © 2011 IBM Corporation

234. Mastering XPages ● Factoids ... ─ Comprehensive 7 Part, 785 page volume ─ IBM Press publication ─ Authored by lead members of XPages development team ─ Features contributions from other key community members ─ Covers all aspects of XPages application development ─ Example-driven approach focusing on practical problems ─ Includes sample NSF downloads ● Available now @ Lotusphere bookstore ● Available online ─ www.ibmpressbooks.com/bookstore/product.asp?isbn=0132486482 ─ www.amazon.com/Mastering-XPages-Step-Step-Application/dp/0132486318 234 © 2011 IBM Corporation

239. Legal Disclaimer © IBM Corporation 2011. All Rights Reserved. The information contained in this publication is provided for informational purposes only. While efforts were made to verify the completeness and accuracy of the information contained in this publication, it is provided AS IS without warranty of any kind, express or implied. In addition, this information is based on IBM’s current product plans and strategy, which are subject to change by IBM without notice. IBM shall not be responsible for any damages arising out of the use of, or otherwise related to, this publication or any other materials. Nothing contained in this publication is intended to, nor shall have the effect of, creating any warranties or representations from IBM or its suppliers or licensors, or altering the terms and conditions of the applicable license agreement governing the use of IBM software. References in this presentation to IBM products, programs, or services do not imply that they will be available in all countries in which IBM operates. Product release dates and/or capabilities referenced in this presentation may change at any time at IBM’s sole discretion based on market opportunities or other factors, and are not intended to be a commitment to future product or feature availability in any way. Nothing contained in these materials is intended to, nor shall have the effect of, stating or implying that any activities undertaken by you will result in any specific sales, revenue growth or other results. IBM, the IBM logo, Lotus, Lotus Notes, Notes, Domino, and Lotusphere are trademarks of International Business Machines Corporation in the United States, other countries, or both. Unyte is a trademark of WebDialogs, Inc., in the United States, other countries, or both. Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. © 2011 IBM Corporation 239

240. SHOW107 The Data Source Session: Take XPages data boldly where no XPages data has been taken before Jim Quill | XPages Developer | IBM Ireland Stephan H. Wissel | LTPA | IBM Singapore © 2011 IBM Corporation

241. Agenda ●Overview – options to connect to data ●The Data Source object model ●Setting up your development environment ●Simple CSV file Data Source ●Debugging your code ●Connecting to RDBMS ●Connecting to Non relational data sources ●Deploying your data source ●Q &A © 2011 IBM Corporation 2

242. Overview – options to connect to data ● Built-in DataSources ─ Domino® View ─ Domino® Document ─ ● SeverSide JavaScript ─ Write custom Java™ code to connect any data source and return that data as an object, array, List, ResultSet, or DataModel will enable XPages controls to consume that data. ─ ● Any control that holds data, for display or editing can be bound to an item of data, a field in a Domino document or a property of a Managed Bean, for example. ● ● Container controls, i.e. DataTable, Repeat, and View Panel can be bound to a single item or a collection of items and will iterate over the data – © 2011 IBM Corporation

244. Overview – options to connect to data ● Built-in DataSources Benefits ─ ─ declaratively add and reuse custom data sources to an XPage, ─ ─ computed properties ─ ─ easy access the data souce in SSJS ─ ─ nest DataSources so contents of one data source can be bound to computed properties of another data source defined on an inner panel that is in a Repeat control ─ ─ control behavoiur via URL parameters ─ ─ add your own query/postSaveEvents, and more © 2011 IBM Corporation

245. Overview – options to connect to data ● Objectives for todays session ─ ─ Write a data source that reads a CSV file from the local filesystem ─ ─ ─ ─ ─ Write a data source that reads data from an RDBMS by executing SQL via JDBC – ● ● ─ © 2011 IBM Corporation ─ ─ ─ ●

247. The Data Source Object Model ● For the two core storage artifacts, View and Documents, XPages provides a convenient mechanism to declaratively add these two data sources to your application without any coding ─ All properties can be computed using JavaScript or an EL expression ─ Tight integration with a set of easy to use Simple Actions for working with Documents and View ─ Ability to specify request parameters to control and influence the behavior of the data source ● ● Within the XPages framework, data sources are based on two key classes ─ com.ibm.xsp.model.AbstractDataSource ─ com.ibm.xsp.model.AbstractDataContainer ─ – © 2011 IBM Corporation

248. The Data Source Object Model ● ─ ComponentBindingObject ValueBindingObject – DataPublishingObject Externalizable StateHolder DataContainer DataSource AbstractDataSource AbstractDataContainer © 2011 IBM Corporation

249. The Data Source Object Model ● AbstractDataSource Responsibilities ─ Data source id management – BeanId – UniqueId ─ RuntimeProperty management – Computed properties can be saved as runtime property so its values doesn't have to be repeatedly calculated ─ State Management – Base properties var, scope, ignoreRequestParams, requestParamPrefix – Property accessors for state of component to be recreated ─ Data Container Management ─ DataPublishing – pushData, popData – publishes the DataModel to request scope using the specified var attribute as the key ● © 2011 IBM Corporation

250. The Data Source Object Model ● Data Container Responsibilities ─ Externalizable support ─ Manages the life cycle of the data – if it doesn't continuously store the data between requests, it knows how to retrieve it. ─ ─ ● © 2011 IBM Corporation

252. Setting up your development environment ● What you need ─ IBM® Lotus Domino® Designer 8.5.2 ─ IBM® Lotus Domino® 8.5.2 ─ IBM® DB2® ─ ─ ● What you should have to hand: ─ Javadoc – XPages Extensibility API Documentation – http://www-10.lotus.com/ldd/ddwiki.nsf/dx/XPages_Extensibility_API_Document ation ─ ─ Wiki – XPages Extensibility API Developers Guide – http://www-10.lotus.com/ldd/ddwiki.nsf/dx/Master_Table_of_Contents_for_XPag es_Extensibility_APIs_Developer_Guide ● © 2011 IBM Corporation

253. Agenda ●Overview – options to connect to data ●The Data Source object model ●Setting up your development environment ●Simple CSV File Data Source ●Debugging your code ●Connecting to RDBMS ●Connecting to Non relational data sources ●Deploying your data source ●Q &A © 2011 IBM Corporation 14

255. Simple CSV Data Source ● Overview ─ Create a New Application ─ Project setup ─ Extend AbstractDataSource – Manages the DataSource properties ─ Extend AbstractDataContainer – Manages the Data life cycle, caching, refreshing ─ Create an xsp-config file that describes the DataSource so it can integrate with Lotus Domino® Designer and the Xpages Framework ● ● © 2011 IBM Corporation

256. Simple CSV Data Source ● Application Setup ─ Grant Anonymous Manager access level File > Application > Access Control... ─ Specify oneuiv2 as the Web theme. File > Application > Properties > Xpages ─ CTRL-S to save changes © 2011 IBM Corporation

257. Simple CSV Data Source ● Switch to the Java™ perspective ─ Window > Open Perspective > Java ● ● Shortcut ─ CTRL-F8 ● ● ● A virtual file system for the NSF ─ organized like a WAR © 2011 IBM Corporation

258. Simple CSV Data Source ● Create a new Source Folder ─ Select the application NSF (ls2011.nsf) ─ Right-Click > New > Source Folder ─ ● Do not use Local as the source folder ─ Java files stored here are actually located on the local workstation file system in the IBM® Lotus Domino® Designer workspace and are not inside the NSF file. ─ When XPages are compiled to Java classes, the intermediate Java source file is written to here. – Can be useful to examine these source files to © 2011 IBM Corporation

260. Simple CSV Data Source ● Appropriate Java Build Path is automatically configured ● ● Select src folder ─ Right-Click > Build Path > Configure Build Path... ─ Select Libraries tab ● © 2011 IBM Corporation

261. Simple CSV Data Source ● Verify the src folder will generate the class files into the expected location (ls2011.nsf/WebContent/ WEB-INF/classes) ● Select src folder ─ Right-Click > Build Path > Configure Output Folder... ─ ● Note: To see the classes folder use the Navigator view ─ Menu > Window > Show Eclipse Views > Navigator © 2011 IBM Corporation

263. Simple CSV Data Source ● Enter the New Java Class details ─ ─ Package: – demo.ls2011.csv ─ ─ Name: – CSVDataSource ─ ─ Superclass: – com.ibm.xsp.model.AbstractDataSource ─ ─ Interfaces: – com.ibm.xsp.model.DataSource ─ ─ Leave inherit abstract methods checked. ● Select Finish © 2011 IBM Corporation

264. Simple CSV Data Source ● The CSV File Data Source has 4 properties ─ ─ csvFilePath – location on the local file system ─ separator – field delimiter – ─ firstLineIsHeader – treat the first line of the CSV file as column headers. – ─ trimWhiteSpace – Postprocessing the data, could be anything you like © 2011 IBM Corporation

265. Simple CSV Data Source ● Theory: Literal values compared to Computed values ─ ─ Property setter called for Literal values – getter will simply return the set value – – ─ SetValueBinding called for Computed values – Getter has to evaluate the corresponding value expression to – AbstractDataSource.RuntimeProperties help optimize reading these values ● © 2011 IBM Corporation

267. Simple CSV Data Source ● Java Bean property accessors ─ Always follow this general structure – If set directly, return the value – Otherwise check for a computed value ● Specifies the location of the target CSV file © 2011 IBM Corporation

271. Simple CSV Data Source ● UniqueId ─ Using a combination of the Data Source properties, than can be repeatedly calculated, construct an id to identity the data souce, such that any property changes that would effect the data would generate a new id. ● Bean Id ─ The key used to store the DataContainer for the DataSource ─ AbstractDataSource calculates beanId, DataSource developer specified how to compose the uniqueId ─ Default scope for DataSources is View Scope ─ If data shared – scope = session – scope = application ─ Then beanId = uniqueId © 2011 IBM Corporation

273. Simple CSV Data Source ● Support changing functionality via request parameters ● http://server/app.nsf/csv.xsp?separator=:&firstLineIsHeader=false ─ ● ● PrefixRequestParam ─ Enable request parameters to be specified for individual data sources ─ ● ● Save is called by XPages Framework if Submit event was triggered © 2011 IBM Corporation

274. Simple CSV Data Source ● State Management ● StateHolder is a JSF interface that must be implemented by components that need to save their state between requests ● Saving and restoring is done as a Serializable object ─ Must have a public no-args constructor ─ ● Component tree is built for the initial request, and then restoring for subsequent postbacks ● If it is not done right, components behave differently and data disappears in subsequent POST requests after the initial GET ─ ● © 2011 IBM Corporation

276. Simple CSV Data Source ● CSVRowData ─ Represents a row of data ● ● Implement DataObject ─ XPages Property Resolver knows about this type ─ For EL expression like item.name instead of calling getName() as is typical for Java Beans the Property Resolver will call getValue(“name”) ● ─ Is also implemented for DominoDocument ─ Similar to ViewRowData Interface used for row data items in a Domino View. ─ Documentation Bug – Interface com.ibm.xsp.model.DataObject is not published. © 2011 IBM Corporation ─ ●

277. Simple CSV Data Source ● CSVRowData ─ Create a new Java Class ─ ─ Package – demo.ls2011.scv – ─ Name – CSVRowData ─ ─ Interfaces – com.ibm.xsp.model. DataObject – java.io.Serializable ● © 2011 IBM Corporation

279. Simple CSV Data Source ● Data Object ● ● ● ● ● ● ● GetValue() ─ #{item.name} – gets the value for the field labeled “name” – ─ #{item[2]} – gets the value for the second field – useful if CSV file doesn't use the first row to specify column names © 2011 IBM Corporation – ─ ─ ●

281. Simple CSV Data Source ● In the Package Navigator, Select the src folder, Right-Click > New > Class to create a New Java Class for the Data Container ● ─ Package – demo.ls2011.csv – ─ Name: – CSVDataContainer – ─ Superclass: – com.ibm.xsp.model. AbstractDataContainer ● ● Select Finish © 2011 IBM Corporation

289. Simple CSV Data Source ● Complex Types in the xsp-config file ─ ─ Used to specify non-primative types in Xpages – Objects ─ Represented using their own tags ─ Can specify a Class or Interface ● ─ ● © 2011 IBM Corporation

290. Simple CSV Data Source ● xsp-config ● ● Declare the namespace ● Descriptive information that wil be used by Domino® Designer ● The class the implements the functionality and property support ● Group-type-ref ─ Base data source properties ─ ● © 2011 IBM Corporation

294. Simple CSV Data Source ● Demo 2 ● ● Switch to the Domino Designer perspective ─ CTRL-F8 > Domino Designer ● Create a new Xpage called xpDemo1 ─ XPages > New Xpage... ─ Name is xpDemo1 ─ Select on the blank XPage design canvas so the XPage design Properties tab appears ● In the XPage Properties tab ─ Open the Data section ─ Click Add and you will see CSV Data Source in the drop down list ─ ● © 2011 IBM Corporation

302. Simple CSV Data Source ● Demo 3 ● ● Button performs partial refresh on outer Panel when clicked. ─ ─ Useful for testing data source State Management ─ ─ If is is wrong, data will disappear after completion of the POST request © 2011 IBM Corporation

305. Debugging you code ● Enable Java debugging on IBM® Lotus Domino® by adding the following lines to notes.ini ─ ─ ─ ─ ─ ─ JavaEnableDebug=1 ─ JavaDebugOptions=transport=dt_socket,server=y,suspend=n,address=8 000 ● ● ─ ● © 2011 IBM Corporation

306. Debugging you code ● Restart IBM® Lotus Domino® and verify that debugging has been enabled by checking the server console for the following message: – > Listening for transport dt_socket at address: 8000 – 1/01/2011 17:08:45 JVM: Java Virtual Machine initialized. – 1/01/2011 17:08:45 HTTP Server: Java Virtual Machine loaded ─ ─ ─ ─ ● © 2011 IBM Corporation

307. Debugging you code ● Instead of switching perspectives, stay in the Domino Designer perspective and open the Navigator and Package Explorer views. ─ Window > Show Eclipse Views > Other... ─ Select Navigator (under General) ─ Click OK ─ ─ ─ ─ ● © 2011 IBM Corporation

308. Debugging you code ● The Navigator opens be default beside the Control palette and the Data palette ● ● One benefit of the Navigator over the Package Explorer is that the Navigator show then compiled Java classes for the application ● ● However it does not have the Right-Click context menus for configuring the Java build path ─ ─ ─ ─ © 2011 IBM Corporation ●

310. Debugging you code ● In Package Explorer, double-click on the class you are interested in debugging to open it. ● Set a breakpoint in your code by double-clicking on the line number for the method you want to debug. ● Notice a small circle icon will appear beside the line. ─ ─ ─ ─ ● © 2011 IBM Corporation

319. Connecting to RDBMS ● Create a read only Data Source that allows a developer to declaratively specify JDBC connection information and an SQL query that retrieves the appropriate data ─ ─ ─ ● © 2011 IBM Corporation

320. Connecting to RDBMS ● Install DB2® ─ Include the sample databases ─ Assumes user is db2admin with password as password ─ ● Locate the JDBC Type 4 driver ─ db2jcc.jar ─ db2jcc_license.jar ─ will need them later ─ ─ ─ ─ ● © 2011 IBM Corporation

328. Connecting to RDBMS ● In the Java perspective, open the Navigator ● Expand the WebContent/WEB-INF folder ● ● Notice there is no lib folder ● ● Select WEB-INF ● Right-Click > New > Folder ─ ─ ─ ─ ● © 2011 IBM Corporation

334. Connecting to RDBMS ● Check the logs ● ● ● Security Exception ─ checkPropertiesAccess() is not managed by AgentSecurityManager ─ Doesn't check if unrestriced users can perform the operation ─ ─ ─ ─ ─ ● Need to move JDBC drivers to trusted location (since call is wrapped by AccessController.doPrivileged() ) ● © 2011 IBM Corporation

335. Connecting to RDBMS ● C:Dominojvmlibsecurityjava.policy ● ● ● ● Choices: ● ─ Store JARs under C:Dominoxspshared – it is a trusted location – XPages ClassLoader will search for JARs here when runtime starts ─ ─ Trust the specific NSF application as a location ● © 2011 IBM Corporation

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

346. Connecting to RDBMS ● Override abstract methods ● ● Connection information and SQL query. ─ Changing the sort order, which still reads the data from the same data source could change the UniqueId, triggering the DataContainer to refresh any cached data ● ● getDataObject gets the data from the DataContainer ─ ─ © 2011 IBM Corporation ─ ─ ●

350. Connecting to RDBMS ● JDBC Data Container ● ● DataContainers are not stored with the DataSource in the view ● The are managed by a scope Bean Manager and are identified by their beanId ─ ─ ─ ─ ● © 2011 IBM Corporation

351. Connecting to RDBMS ● JDBC Data Container ● ● Get the data ● ● Other stragegy is to get the data as part of the DataSource and just have container manage its lifecycle ─ Can it be cached ─ Does it need to be refereshed ─ Resource pooling ─ ─ ─ ─ © 2011 IBM Corporation ●

353. Connecting to RDBMS ● JDBC Data Container ─ Leverage FacesContextListener to manage the lifecycle of the data and caching stratagies – beforeRenderingPhase() – beforeContextReleased() ─ ─ ─ ─ ● © 2011 IBM Corporation

354. Connecting to RDBMS ● JDBC Data Container ─ ─ Implements Externalizable ─ ─ Class handles serialization of each property itself ─ ─ Optimization to avoid the serialization code having to intropsect and figure out all the datatypes. ─ ─ ● © 2011 IBM Corporation

355. Connecting to RDBMS ● Create ResultSetModelEx ● ─ Extends TabularDataModel – better integration with XPages Pager control for ResultSets ─ ─ Delegates to ResultSetDataModel ─ ─ ─ ● © 2011 IBM Corporation

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

357. Connecting to RDBMS ● ResultSetModelEx ● ● Pager estimates number rows and ask data model if it knows if rowCount is bigger than current maxCount ● ● For the current page, always return the current page range + 1 – causes the Pager to indicate that there are more rows ─ ─ ─ ─ © 2011 IBM Corporation ●

359. Connecting to RDBMS ● ResultSetModelEx ─ ─ If isRowAvailable returns false from the delegated ResultSetDataModel then we know we have found a potential value for the actual row count ─ HasMoreRows() will start using this value and since it will be less than the current deduced max in the pager, it will readjust based on this value. ─ © 2011 IBM Corporation ─ ─ ●

370. Connecting to RDBMS ● Pager tries to deduce last page ● ...Next indicates more pages ● ● Keeps increasing until no row is found, then Pages adjusts last page ● Next indicates a max count found ● ● ● ─ ─ © 2011 IBM Corporation ─ ─ ●

371. Agenda ●Overview – options to connect to data ●The Data Source object model ●Setting up your development environment ●The first data source ●Debugging your code ●Connecting to RDBMS (Part 2: CRUD) ●Connecting to Non relational data sources ●Deploying your data source ●Q &A © 2011 IBM Corporation 132

373. Connecting to RDBMS(2) ● Create a JDBC Data Source that supports working with individual rows in a table. Should support operations such as: ─ ─ (C) inserting a new row ─ (R) selecting a specific row ─ (U) updating an existing row ─ (D) deleting a row ─ ─ ● Like a DominoView -> DominoDocument, Master -> Detail type relationship ● ─ JDBCQueryDataSource – works with several rows – ─ JDBCRecordDataSource – works with a single row © 2011 IBM Corporation

376. Connecting to RDBMS(2) ● Create a New Java Class ─ Select the ls2011 package ─ Right-Click, select – New > Class ─ ─ ─ ─ ─ ─ ● Use CTRL-F8 to switch perspectives (if necessary) ● © 2011 IBM Corporation

378. Connecting to RDBMS(2) ● Constants ─ Not all used in current implementation ─ ─ JDBC Driver properties ─ ─ Standard XPages (Domino oriented URL parameters ─ ─ Actions – New, Open, Edit ● © 2011 IBM Corporation

380. Connecting to RDBMS(2) ● Create a New Java Class ● ● A class with helpful convenience methods for working with JDBC, e.g. open/close connections, getting column information, setting types, etc. ● ● Package: ─ demo.ls2011.jdbc4 ─ ● Name: ─ JDBCUtil ● © 2011 IBM Corporation

384. Connecting to RDBMS(2) ● Utility method to for setting the appropriate type for the columns when setting parameters for a JDBC PreparedStatement ● ─ not all types covered – Numbers – Characters ● © 2011 IBM Corporation

387. Connecting to RDBMS(2) ● Create a New Java Class ● ● Package: ─ demo.ls2011.jdbc4 ─ ● Name: ─ JDBCAbstractDataSource ● ● Modifiers: ─ public abstract ─ ● Superclass: ─ com.ibm.xsp.model.Abstract DataSource ● © 2011 IBM Corporation

388. Connecting to RDBMS(2) ● Imports that can be added as the abstract data source class is developed ● ● Has the abstract modifier ● ● This class will be extended later on with a concrete class that will implement the row oriented specifics of the data source ● ● © 2011 IBM Corporation

389. Connecting to RDBMS(2) ● Specify member variables that represent properties for the JDBC-based data source ─ server ─ port ─ database, etc ─ ● parameters is as List ─ used to store name-value (com.ibm.xsp.Paramster) pairs that can be used to pass information to the data source. ─ ● ● © 2011 IBM Corporation

390. Connecting to RDBMS(2) ● Create property accessor methods ─ server ─ port ─ ● Follow the standard 'template' for getters ─ 1) check if instance variable is set ─ 2) check for a corresponding value binding (if value can be computed) ─ 3) retrun null or default for primitive (int etc.) types ● ● action ─ 'read only' property ─ set via request parameter – action=newDocument © 2011 IBM Corporation

391. Connecting to RDBMS(2) ● More property accessors ─ database ─ user ● If RuntimeProperties is implmemented, get it here. ● ● Extend the standard 'template' for getters ─ 1) if using RuntimeProperties, get it from there ─ 2) check if instance member variable is set ─ 3) check for a corresponding value binding (if the value can be computed) ─ 4) retrun null or default for primitive (int etc.) types © 2011 IBM Corporation ● ●

392. Connecting to RDBMS(2) ● More properties ─ password ─ selectString ● ● selectString ─ idea was that whether one row is indented to be returned (JDBCRecordDataSource), or several (JDBCQueryDataSource). ─ oth have a SQL select statement in common, so property is in abstract class – then decided to modify/override with concurrency column info (not fully implemented) ● © 2011 IBM Corporation ●

393. Connecting to RDBMS(2) ● More properties ─ keyColumn – primary key – ─ tableName – used for getting database metadata – ─ SortOrder – not implemented. ● ● Optimize – collect metadata during Connection/Data Source definition ● © 2011 IBM Corporation

394. Connecting to RDBMS(2) ● ● UniqueId ─ An identifier that distinguishes this JDBC data source from other JDBC data sources – can be repeatedly re-constructed form the data source properties ─ ─ used as the name for storing data in scope (if shared) ─ ─ connection information + request parameter info + select statement © 2011 IBM Corporation

395. Connecting to RDBMS(2) ● Read general request parameters ─ action ─ sortOrder ● ● Abstract methods sub-classes must implement ─ isReadOnly() ─ getDataObject() ─ load() ─ save() ● ● Helper methods for connection URL and opening the JDBC connection © 2011 IBM Corporation

398. Connecting to RDBMS(2) ● Next... ● ● create a helper class JDBCConcurrencyInfo ● ─ Not really used. Keep in mind that it (or this feature) will be required for taking this sample further for production use. ● ● © 2011 IBM Corporation

400. Connecting to RDBMS(2) ● Concurrency ─ Pessimistic – RDBMS specific ─ ─ Optimistic – which column provides the 'timestamp' that can be compared for row updates – ─ Force – Last Writer Wins – Not really a good idea ● ● © 2011 IBM Corporation

402. Connecting to RDBMS(2) ● Next... ● ● Create a concrete class that implements DataObject ─ ─ JDBCRecord ● ● Purpose ─ Enables the data that are returned to be simply referenced with an EL expression using the data field/column name ● ● © 2011 IBM Corporation

403. Connecting to RDBMS(2) ● Create a New Java Class ● ● Name: ─ JDBCRecord ● ● Interfaces ─ com.ibm.xsp.model. DataObject – Known interface by the XPages PropertyResolver, calls getValue(“<prop>”) ─ java.io.Serializable ● ● © 2011 IBM Corporation

404. Connecting to RDBMS(2) ● When the XPages Framework calls ─ DataSource.getDataObject() ─ which in turn calls ─ DataContainer.getRecord() ● This is the returned object ● Is essentially the BackingBean for the part of the UI that displays the data from the Data Source ● ● wrappedData ─ JDBC ResultSet ─ transient - not serializable need to be managed ● © 2011 IBM Corporation

405. Connecting to RDBMS(2) ● Constructor ─ ResultSet – wrapped ─ UniqueId – Primary Key Column for the record ─ Should be a List<String> ─ ● Get the Column Types for each of the Columns based on the ResultSet meta data ● ● selectSQL ─ used to recreate the ResultSet as necessary ● © 2011 IBM Corporation

407. Connecting to RDBMS(2) ● ● The DataContainer implementation will callback to the JDBCRecord before and after the de/serialized to give JDBC an opportunity to do anything it needs ● © 2011 IBM Corporation

408. Connecting to RDBMS(2) ● discardWrappedObject ─ ResultSet is closed before serialization. ─ ─ ● Several other methods not yet fully implemented that will be useful in the future: ─ CheckRecordValidity() – row may been deleted between requests ─ ● ● © 2011 IBM Corporation

410. Connecting to RDBMS(2) ● Next... ● ● Create a concrete class that extends AbstractDataContainer ─ ─ JDBCRecordDataContainer ● ● Purpose ─ Manages the life-cycle of the data in a stateless request response environment ─ Good place for implementing a caching strategy ● ● © 2011 IBM Corporation

411. Connecting to RDBMS(2) ● Create a New Java Class ● ● Package: ─ demo.ls2011.jdbc4 ─ ● Name: ─ JDBCRecordDataContainer ─ ● Superclass: ─ com.ibm.xsp.model.Abstract DataContainer ● ● © 2011 IBM Corporation

412. Connecting to RDBMS(2) ● com.ibm.xsp.model.Abstract DataContainer ● ─ contains some basic support for making the data source Externalizable ● ● Need to implement the required serialize and deserialize methods ● © 2011 IBM Corporation

413. Connecting to RDBMS(2) ● ● JDBCRecord ─ the data object ● ● FaceContectListener ─ used to discard resources at the end of the request ● ● In this implementation the DataSource creates the JDBCRecord and passes it into the Constructor ● © 2011 IBM Corporation

414. Connecting to RDBMS(2) ● FacesContextListener ─ Can use this listener to manage the data through the various phases of the JSF Lifecycle ─ ● ● ● getRecord() ● ● Called from DataSource.getDataObject() – Xpages Framework entry point for Data Source data © 2011 IBM Corporation ●

415. Connecting to RDBMS(2) ● Externalizable ● ─ For Serialization when the data to be serialized is complex – since the datatype are known can use the API to specify the type avoid the introspection – readBoolean() – readChar() – readObject() – ... – ● ● © 2011 IBM Corporation

417. Connecting to RDBMS(2) ● Next... ● create a concrete implementation that extends JDBCAbstractDataSource ● that will work with a single row of data in a table ● ● It will support operations to ─ (C)reate -> Insert ─ (R)ead -> Select ─ (U)pdate -> Update ─ (D)elete-> Delete ● ● © 2011 IBM Corporation

418. Connecting to RDBMS(2) ● Create a New Java Class ● ● Package: ─ demo.ls2011.jdbc4 ─ ● Name ─ JDBCRecordDataSource ● ● Superclass: ─ demo.ls2011.jdbc4. JDBCAbstractDataSource ● © 2011 IBM Corporation

419. Connecting to RDBMS(2) ● Required imports ● ● JDBCRecordDataSource specifies the SQL required for manipulating the data ● ● MethodBinding ─ Support actions that can be called before and after saving row ● ● © 2011 IBM Corporation

423. Connecting to RDBMS(2) ● If no action is specified, assumes newDocument ● ● Whenever the XPages component tree is being constructed or traversed any data controls are 'published' ● ● DataPublisher() calls getDataObject() ● getDataContainer() is implemented in AbstractDataSource ─ checks uniqueId() ─ calls load() ● © 2011 IBM Corporation ● ●

425. Connecting to RDBMS(2) ● Invoke the Data Source Action ─ push() ─ invoke() ─ pop() ● ● If it's a new document, then beforehand, for example, queryNewDocument, there is no record/document, so no data to push to request scope, so in this case, record would be null. ● © 2011 IBM Corporation

426. Connecting to RDBMS(2) ● Read JDBCRecordDataSource specific request parameters ● ● JDBCConstants ─ URL_PARAM_ID – documentId ● ● DataSource will be published using the var attribute ─ record1 ● Can publish the data using several identifiers, ─ currentDocument ─ © 2011 IBM Corporation

428. Connecting to RDBMS(2) ● (R)ead ● ● JDBC PreparedStatement ● ● If documentId not set in URL, or ignoring request parameters for this data source look into the supplied Parameters ● ● ● If asked to read a row, but no PK specified, default to Create/Insert a new row © 2011 IBM Corporation

433. Connecting to RDBMS(2) ● For UPDATE, the PK value should be specified in the WHERE clause ● ● ● ● executeUpdate() ─ should update/insert 1 row ● ● ● If it was INSERT – get the PK value so it can be stored in the JDBCRecord ● ● © 2011 IBM Corporation

438. Connecting to RDBMS(2) ● – com.ibm.xsp.model.group AbstractDataSource .DataSource JDBCAbstractDataSource jdbcAbstractDataSource.xsp-config JDBCRecordDataSource jdbcRecordDataSource.xsp-config © 2011 IBM Corporation

446. Connecting to RDBMS(2) ● <complex-type> ─ specifes an Object with properties ● <display-name> ─ will be shown in Domino Designer ● <complex-id> ─ identifier ─ ● <complex-class> ─ fully qualified implementing class ● ● © 2011 IBM Corporation

447. Connecting to RDBMS(2) ● More properties.... ● ● ● ● <property-class> ─ javax.faces.el.MethodBinding ─ ● <property-extension> ─ DominoDesigner directive ─ <method-binding-property> – true © 2011 IBM Corporation

448. Connecting to RDBMS(2) ● <group-type-ref> ─ to include properties from other .xsp-config definition files ─ ● <complex-extension> ─ <tag-name> – jdbcRecordDataSource ─ <base-complex-id> – dataInterface ● ● © 2011 IBM Corporation

468. Connecting to non relational data sources ● XML ● Web Services (REST/SOAP) ● etc ● ● Same approach as two previous examples ● ● Extend AbstractDataSource to define what properties the data source has ● ● Extend AbstractDataContainer to manage the life-cycle of the data in the context of a disconnected web application where the data is only live for the duration of the request ● ● © 2011 IBM Corporation ─ ─ ─ ─ ●

470. Deploying your data source ● To create a sharable library (OSGi Plugin), see ─ ─ http://www-10.lotus.com/ldd/ddwiki.nsf/dx/Creating_an_XPag es_Library ● ● For deployment on Lotus Domino® and Lotus Notes® Client, see ─ ─ http://www-10.lotus.com/ldd/ddwiki.nsf/dx/Deploying_XPage_ Libraries ─ ─ ─ ─ ● © 2011 IBM Corporation

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

478. Legal Disclaimer © IBM Corporation 2011. All Rights Reserved. The information contained in this publication is provided for informational purposes only. While efforts were made to verify the completeness and accuracy of the information contained in this publication, it is provided AS IS without warranty of any kind, express or implied. In addition, this information is based on IBM’s current product plans and strategy, which are subject to change by IBM without notice. IBM shall not be responsible for any damages arising out of the use of, or otherwise related to, this publication or any other materials. Nothing contained in this publication is intended to, nor shall have the effect of, creating any warranties or representations from IBM or its suppliers or licensors, or altering the terms and conditions of the applicable license agreement governing the use of IBM software. References in this presentation to IBM products, programs, or services do not imply that they will be available in all countries in which IBM operates. Product release dates and/or capabilities referenced in this presentation may change at any time at IBM’s sole discretion based on market opportunities or other factors, and are not intended to be a commitment to future product or feature availability in any way. Nothing contained in these materials is intended to, nor shall have the effect of, stating or implying that any activities undertaken by you will result in any specific sales, revenue growth or other results. IBM, the IBM logo, Lotus, Lotus Notes, Notes, Domino, and Lotusphere are trademarks of International Business Machines Corporation in the United States, other countries, or both. Unyte is a trademark of WebDialogs, Inc., in the United States, other countries, or both. Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. © 2011 IBM Corporation 239

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

More Related Content

What's hot (20)

Viewers also liked (19)

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

More from Stephan H. Wissel (9)

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