webinar: xpages goes relational!

©2011 IBM Corporation

Webinar: XPages Goes Relational!November 18th, 2011

Andrejus ChaliapinasSenior Software Developer | XPages, IBM Ireland

● =

© 2011 IBM Corporation 2

Agenda

● XPages Extension Library OpenNTF 8.5.3 and IBM position in regards to official support

● Installation steps on server/client● Demo of installation steps● Stage of XPages Relational support implementation● New data sources for RDBMS connectivity● Additionally required manual connection configuration step● @Functions available for Server Side Javascript● Demo using DB2 Express instance● Q&A


XPages Extension Library OpenNTF 8.5.3 and IBM position in regards to official support● Currently could be found at http://extlib.openntf.org/ where all latest

demos are posted and discussion threads are available

● Download from Downloads/Releases section

http://extlib.openntf.org/

http://extlib.openntf.org/


XPages Extension Library OpenNTF 8.5.3 and IBM position in regards to official support (cont.)● Notes/Domino 8.5.3 targeting version was initially released on October

17th, 2011.● As of November 18th latest release is provided via file named:

ExtensionLibraryOpenNTF-853.20111027-1245a.zip● From News section you should read this important post:

XPages Extension Library - News: October 20th Release - Notes from Peter Janzen where you'll find such statement about this release:

“It sets the stage for many of the controls and objects to become a supported set of features for Lotus Notes and Domino.” That means that while this project will continue its existence as an OpenNTF project – part of it with the same code base will be officially supported by IBM.

● There are now 2 sets of plugins included in OpenNTF delivery - “extlib” and “extlibx”. The one called “extlibx” contains now some experimental code (like XPages Relational) and will be added to official support when it will be mature enough for that.

http://www.openntf.org/Projects/pmt.nsf/downloadcounter?openagent&project=XPages%20Extension%20Library&release=853.20111027-1245a&unid=5640D4A0F4BEE43B862579370070CA75&attachment=ExtensionLibraryOpenNTF-853.20111027-1245a.zip

http://www.openntf.org/internal/home.nsf/news.xsp?databaseName=CN=NotesOSS2/O=NotesOSS!!Projects%5Cpmt.nsf&documentId=A9E0E64F4DD7BC6F8625792C001E2E43&action=openDocument




Installation steps on server (template to use)

● XPages Extension Library delivery ZIP file contains 2 Eclipse based update sites:

updateSiteOpenNTF.zip (to be installed on Domino server)

updateSiteOpenNTF-designer.zip (to be installed in Domino Designer)● Installation on server side should be done using XPages Extension

Library Deployment in Domino 8.5.3 and IBM XWork Server technique described in Lotus Notes and Domino Application Development wiki:

Involves creation of a new NSF application based on updatesite.ntf template and import of updateSiteOpenNTF.zip into it

Requires specification of OSGI_HTTP_DYNAMIC_BUNDLES variable inside your server's notes.ini file to point to update site NSFs

Uses additional safeguards when loading plugins (ACL)

http://www-10.lotus.com/ldd/ddwiki.nsf/dx/XPages_Extension_Library_Deployment




Installation steps on server (verification)

● For Domino server to pick up those new artifacts you need to restart your Domino server issuing console command restart task http

● To verify that the library is properly installed - you should use such OSGI command on server console:tell http osgi ss com.ibm.xsp.extlib


Installation steps on server (additional plugins)

● For connection to DB2, MS SQL, mySQL, Oracle and other databases you may need to prepare your own plugin, which will wrap specific database JDBC driver (usually available as 1 or 2 vendor's jar files) and then deploy it either to Domino server or Designer client or both

● Currently sample DB2, MS SQL, mySQL (Oracle to follow soon) plugins/update sites with source code are provided on OpenNTF web site

● For the purpose of this webinar we'll use freely available DB2 Express-C v9.7.4 RDBMS

● We'll use also Sample DB2 driver update site available as Extlib_8.5.3_DB2_Driver_updateSite201110201044.zip. This update site wraps DB2 JDBC driver, available for download from IBM site

● Verification: tell http osgi ss extlib.driver.db2

http://www.openntf.org/internal/home.nsf/response.xsp?action=openDocument&documentId=D3AE5ED15BE784358625792F00362632&MainID=C3103EC4E9FE5DDA86257901006837F1


http://www.openntf.org/internal/home.nsf/response.xsp?action=openDocument&documentId=87EBF546D95FE7808625792F004E27B8&MainID=C3103EC4E9FE5DDA86257901006837F1

http://www.openntf.org/internal/home.nsf/response.xsp?action=openDocument&documentId=87EBF546D95FE7808625792F004E27B8&MainID=C3103EC4E9FE5DDA86257901006837F1

http://www.openntf.org/internal/home.nsf/response.xsp?action=openDocument&documentId=F056C0DC14187FCC8625792F007088D6&MainID=C3103EC4E9FE5DDA86257901006837F1

http://www.openntf.org/internal/home.nsf/response.xsp?action=openDocument&documentId=F056C0DC14187FCC8625792F007088D6&MainID=C3103EC4E9FE5DDA86257901006837F1

http://www-01.ibm.com/software/data/db2/express/download.html






Installation steps on server (demo database)

● With XPages Extension Library you get also demo application, called XPagesJDBC.nsf, which demonstrates main functionality currently available for Relational support. You need to copy it to your server (here we'll have it under <Domino_Data>/demo directory) and sign with some user/server ID. If steps were done correctly till this moment - you'll see:


Installation steps on server (things to notice)

● At this moment you cannot open yet XPagesJDBC.nsf demo application inside your Domino Designer if you have option Project → Build Automatically switched on (which is default), because we don't have yet required plugins installed for Domino Designer and you'll get a lot of compilation errors making demo application inaccessible from your server

● With Extension Library delivery ZIP you get only embedded Derby database driver installed for quick testing and demo application is configured to use it. We'll change that later using Domino Designer to use DB2 driver instead


Installation steps on client (preferences)

● Installation for Domino Designer requires Enable Eclipse plug-in install preference to be enabled

● After that next steps are done via File → Application → Install menu and selection of updateSiteOpenNTF-designer.zip file


Installation steps on client (update site)

● You add that zip as location to install from:


Installation steps on client (features list)

● One of the features inside it is directly related to XPages Relational support:


Installation steps on client (verification)

● To verify installation inside Domino Designer you need to open Help → About IBM Lotus Domino Designer menu, click Plug-in Details button, sort by Plug-in Id and check if you have these:


Installation steps on client (usage in apps)


Installation steps on server/client live demo

● Live demo for about 15-20 minutes


Stage of XPages Relational support implementation● Leverages JDBC to connect to the relational databases

Accesses any database with a JDBC driver available

The data is accessed directly: no synchronization needed with NSF● Connections currently could be defined only within NSF

A NSF contains a new file design element (with .jdbc extension) for defining database specific connections. Such design element editing requires switch to Navigator view currently and is located in WebContent/WEB-INF/jdbc directory.

● Global connections definition on server will be addressed later● Uses a connection pool to optimize the use of connections

Simple connection pool provided, plan to add support of Apache DBCP


New data sources for RDBMS connectivity

● There are 2 new data sources you could easily make to be used by your xp:viewPanel control:

JDBC Query data source, which provides Read Only access for RDBMS

JDBC RowSet data source (uses the standard CachedRowSetImpl), which allows you to edit (create/update/delete) RDBMS data

● Access to different RDBMS table's fields is made through used for Domino views xp:viewColumn controls thus making such usage transparent for developer by hiding all details

● At this moment Domino Designer tooling for table definition retrieval for easier column/field selection is under development and you may need to know ahead your table DDL to specify properly columnName attribute of xp:viewColumn control


New data sources for RDBMS connectivity (choices)● This screenshot below demonstrates how you could select those 2

new data sources using Properties area (in this case for xp:viewPanel control):


New data sources for RDBMS connectivity (SQL queries)● The SQL query can be provided using either

A table name – The runtime will generate a select * from <table name> A SQL query, from a data source property (static or computed)

A SQL file resource (*.sql) containing the SQL statement

● The size of the result set can be computed so the pager can display the actual number of pages

Enabled using the calculateCount property, which is false by default

Generates a hidden select count(*) to get the exact size

• Just replaces the select part of the original query by count(*)• A specific count query can be provided for performance reasons (ex: avoid

ordering...)


New data sources for RDBMS connectivity (parameterizing)● A data source can either point to a named connection or a JDBC URL

Named connections are heavily advised as they take advantage of a connection pool, and they are easier to manage as they are centrally defined

• The JNDI prefix can be omitted in the name JDBC URL are for debugging purposes only

● The SQL statement can either be defined (or computed) from a data source property, or defined in a separate file design element (*.sql)

● Parameters, matching the '?' in the SQL query, are also defined at the data source level. The order of the parameters must match the order of '?' in the SQL query

sqlTable: a simple table namesqlQuery: a general sql querysqlFile: points to a .sql design element


New data sources for RDBMS connectivity (CRUD)● In XPagesJDBC.nsf demo application you'll find sample of CRUD

provided (XPage called JDBC_RowSetDatasource.xsp) through which you could create/update/delete records in external RDBMS


Additionally required manual connection configuration step (for DB2 here)● To configure your DB2 connection you need to create new design

element (let's call it db2demo.jdbc) and specify in it JDBC driver class to be used, database name and user's credentials:

<jdbc><driver>com.ibm.db2.jcc.DB2Driver</driver><url>jdbc:db2://testvm:50000/DEMO</url><user>demo</user><password>test123</password>

</jdbc>

● Important: part of name before “.jdbc” of such design element, which is in this case “db2demo” will be used for JDBC data sources configuration

● Reminder: db2demo.jdbc design element should be saved into your application's WebContent/WEB-INF/jdbc folder


@Functions available for Server Side JavaScript

● Currently these @Functions are implemented:

@JdbcInsert (sample provided in JDBC_AtFunctions.xsp)var v = {

id: id,firstName: "Albert",lastName: "Einstein",city: "Boston",state: "MA"

}var c = @JdbcInsert("db2demo","users",v)

@JdbcUpdate (sample provided in JDBC_AtFunctions.xsp)var v = {

city: "Boston",state: "MA"

}var c = @JdbcUpdate("db2demo","users",v,"id=?",id)

@JdbcDelete (sample provided in JDBC_AtFunctions.xsp)var c = @JdbcDelete("db2demo","users","id=?",id)


@Functions available for Server Side JavaScript (continued)

@JdbcExecuteQuery (sample provided in JDBC_TableMetaData.xsp)var sql = "select * from "+tb;var rs = @JdbcExecuteQuery('db2demo',sql);

@JdbcDbColumn (sample provided in JDBC_StaticViewPanelParam.xsp)@JdbcDbColumn("db2demo","states","state")

@JdbcGetConnection


Demo of JDBC data sources using DB2 Express instance● Live demo for about 15-20 minutes● For XPagesJDBC.nsf to setup test data inside your DB2 instance you

would need these changes:

Uncomment these lines inside xpages.DataInitializer Java class:// case GENERIC: {// createTables_Derby();// } break;

Specify your connection name inside xpages.DBUtil Java class:this.connectionName = "db2demo";

Specify the database schema:public String getSchema() {

return "DEMO";}


Q & A

webinar: xpages goes relational!

Documents