Using DB2 in XPages Part 4: Setting up the Database Connection for use with SSJS

In this fourth entry in my blog series on XPages and DB2, I will explain the additional steps necessary for SSJS access, if using parameterized connection information. This post isn't intended to stand alone but build on what I discussed in part 3.  I will say this, if you decide to store your credentials in the db2.jdbc XML file then everything here in this post is unnecessary for you. If you are an XPages developer and have never had made your own custom tags, then this post might serve as a general example on how to go about doing that.

Create Custom Control for adding your Customized Connection Manager

To take advantage of our connection manager java class (described in part 3) in SSJS, we need to create a custom control for adding the connection manager to each page. For simplicity, we name it the same thing as our java class, which is XYZConnectionManager.  In order to make our own custom control, we have to create an faces-config extension file, or add to it, if we already have one. We cannot put our entry directly in the main face-config as this doesn't compile. The faces-config extension is a separate file that you create when necessary for the purpose of creating custom tags.

This file should be copied into the WEB-INF folder alongside the faces-config file using the Package Explorer.

Here is what the contents of the file look like.

<faces-config> 
  <faces-config-extension> 
     1<namespace-uri>http://www.xyzCompany.org/xpages/component</namespace-uri> 
     2<default-prefix>xyz</default-prefix> 
  </faces-config-extension> 
  <component> 
     <display-name>XYZ Connection Manager</display-name> 
   3<component-type>com.ibm.xsp.extlib.relational.jdbc.JdbcConnectionManager</component-type> 
   <component-class>org.xyz.atm.util.XyzConnectionManager</component-class> 
   <component-extension> 
     <base-component>com.ibm.xsp.extlib.relational.jdbc.JdbcConnectionManager</base-component> 
      4<tag-name>XyzConnectionManager</tag-name> 
      <designer-extension> 
      <category>XYZ Custom</category> 
      <generate-id>true</generate-id> 
      5<in-palette>true</in-palette> 
      <visible>true</visible> 
      </designer-extension> 
    </component-extension> 
    </component> 
</faces-config> 

Essentially what you are doing here is creating your own tag here that you can add to any page.  In this case, you will get access to the relational controls for whatever page in which you add the custom tag.  This would replace adding the built-in JDBCConnectionManager to your page.

Here is a explanation of key parts of this file:

1 - The namespace URI needs to only be a unique value.  It does not need to resolve to a real URL, just as the XSP namespace does not resolve to a real URL.

2 - This is the prefix we chose for our tag. This is analogous to "xp" for core controls, or "xe" for extension library controls.

3 - This maps the control to the java class we want to use

4 - This is the name of the tag that we show in our code

5 - Setting this to true, make the control show up in our palette where we can drag it onto a page

Sample Usage:
1) Include the new name space in your xpView tag at the very top
xmlns:xyz="http://www.xyzcompany.org/xpages/component"

2) Drag your control on the page using the palette or type it in the source. 
<xyz:XyzConnectionManager id="XyzConnectionManager1"></xyz:XyzConnectionManager> 

You will want to put this tag on any page that uses the relational controls, or put this in your application layout once, which makes it available on any page.

Known Issue:
For some reason, Designer often "forgets" about the faces-extension file and creates an unknown tag error on every page where it is used.  If you go and edit something in the faces-extension file and save the "change" (without really changing anything) and the clean your application the errors will go away. It sometimes takes two cleans.

Next Post

In my next post, I will finally get to the part where I can show how we use DB2 as our backend datastore. I will start with how to write a simple SELECT statement to populate a page.