Creating a SQL Service with IBM WebSphere Portlet Factory May, 2009 Copyright International Business Machines Corporation 2009. All rights reserved. This article with the accompanying sample shows you how to use IBM WebSphere Portlet Factory Version 6.1.2 (hereafter called Portlet Factory) to create a service that uses data from a relational database. The sample service supports a range of database functionality, with full create-read-update-delete (CRUD) support. This article is one in a collection of articles and samples that illustrate techniques for developing with Portlet Factory. See the Portlet Factory Product Documentation page for a complete list of these. For an introduction to developing with Portlet Factory, you may want to look at the introductory tutorials that are available both in the product help and on that web site. Prerequisites You should have a basic familiarity with Portlet Factory and be able to create and run Portlet Factory models. Some familiarity with SQL is desirable but not required. Introduction to creating services from a relational database As with any service provider model, you will use the Service Definition and Service Operation builders to define the service. To provide access to database data, you will use the SQL Call builder. Since each SQL Call builder accesses one SQL statement or operation, you will generally need to have a SQL Call builder for each service operation. As shown in this sample, SQL Call can be used to implement any kind of database operation. Inputs to SQL-based services are typically used as query parameters in SQL statements. The mapping between service operation inputs and SQL query parameters is done in the Service Operation builder.
Figure 1. This diagram shows a conceptual picture of the sample application with provider and consumer models. Each Service Operation is implemented using a SQL Call builder. Portlet (Consumer) Model SQL Service Provider Model Service Consumer Service Definition Service Operation Service Operation Service Operation SQL Call SQL Call SQL Call SQL Call Database Sample description Here are some of the techniques illustrated in the sample code. Creating a service using SQL Call with complete CRUD (create, read, update, delete) functionality. The service has operations for list, search, details, update, delete, and create. Most of the SQL Calls use query parameters which are exposed as service operation input parameters. Using the View & Form builder for list, detail, and update functionality. The SqlEmployeeConsumer model uses the Service Consumer builder to make the service available, then uses the View & Form builder to create a list page, a details page, and an update page. The EMPNO column is used as a link to the details page, and the input used to retrieve the employee details data is specified in the Overridden Inputs section of the Service Consumer builder. The value for this input is taken from the employees_selectedrowdata variable. This SelectedRowData variable is created by the View & Form builder and is automatically populated with the selected row contents whenever the user clicks on a row link. The text labels and formatting for the consumer model are handled with a Rich Data Definition file which is applied in the Service Consumer builder. Pre-processing of service operation input values. The searchforemployees operation uses the Additional Processing feature of the Service Operation builder to check search inputs for null. The pre-processing of inputs is done in the checksearchinputs
method where any null inputs are converted to % in order to be used with the LIKE condition of the SQL statement. Specifying nice field names for SQL Call query parameters. When the SQL Call builder generates an input schema from the SQL query parameters, the generated field names are very generic names like Parameter1Value, Parameter2Value. There are a couple of techniques that can be used to get nicer field names for your service operation inputs. You could use a hand-created schema and map fields to that schema in the Service Operation builder. Alternatively you can use the approach taken for the updateemployeerecord operation. In this case, the EmployeeDetails structure from the getemployeerecordsql operation is used as the input schema. This structure has nice field names taken from the database schema. The mapping between the Parameter1Value-style names and the nice field names is done in the Input Field Values table for updateemployeerecord. A similar approach is taken with the searchforemployees operation. Creating a lookup table from service operation data. The getdepartments service operation is used to get a list of department numbers with corresponding department names. In the consumer model, the Lookup Table builder is used to create a departments lookup. This lookup is applied to the department field on each of the pages, to display the name of the department instead of the department number. On input pages such as the update page, the department field is automatically displayed as a drop-down list. Using a profile set to control data source name. In all the SQL Call builders, the data source name is profiled to the same entry in the supplied profile set. This enables you to change the name of the data source in one place, and have all the builders automatically use the new value. This technique can be used for all the builders in a model as shown here, and it can also be used across a whole set of models in a project, if all the models use the same profile set entry to control the data source name. Using View & Form builder for creating new records. The createform View & Form builder is used to make an input page for creating new employee records using the createemployeerecord service operation. In this case, the results page of View & Form builder is used only to show a confirmation message and a link back to the main page since the createemployeerecord operation does not return any data. Table 1. Sample package contents Filename and location WEB-INF/models/samples/sql_service/ SqlEmployeeService WEB-INF/models/samples/sql_service/ SqlEmployeeConsumer WEB-INF/models/samples/sql_service/ SqlEmployeeStub WEB-INF/samples/sql_service/ Description Service model that uses SQL Call builders to access a relational database. Presentation model with pages that access the service. A stub service model generated from the real service model. Rich Data Definition file used
employee_datadef.xml WEB-INF/profiles/ samples.sql_service.sqlservicedatasource.pset in the consumer model. Profile set for storing the J2EE data source name. Figure 2. This screen capture shows the running service consumer model showing a list of employees.
Figure 3. This screen capture shows the input form for updating an employee record. Instructions for running the sample To run the sample application: 1. Download the sample ZIP file and import it into a project using the File, Import, WebSphere Portlet Factory Archive command. 2. Create a JDBC Provider and a J2EE Data Source to access the Employee sample database. See instructions below to create these resources and to obtain IBM WebSphere Portlet Factory Sample DB. 3. Open the SqlEmployeeService model and run it. The operations you can easily run in the test harness are getemployeelist, getemployeerecord, searchforemployees, and getdepartments. 4. Open the consumer model, SqlEmployeeConsumer, and run it. Try the various operations that are available.
Configuring Database Connectivity For Portlet Factory 6.1.2 users, please select the Application server below that you will be using for your sample. WebSphere Application Server Community Edition, installed with WebSphere Portlet Factory. WebSphere Application Sever Community Edition, installed separately from Websphere Portlet Factory WebSphere Application Server Standalone 6.x or with WebSphere Portal 6.x. For Portlet Factory versions released prior 6.1.2, please follow Instructions for Portlet Factory versions released prior to 6.1.2 Configuring Websphere Application Server Community Edition installed with WebSphere Portlet Factory Follow these steps to enable your project to use the sample database that comes preconfigured on the WebSphere Application Server Community Edition (WAS CE) server that was installed with Portlet Factory 6.1.2. 1. Edit your projects WEB-INF\bin\deployment\geronimo-web.xml file. Uncomment the EmployeeDatasource dependency and resource references. 2. Edit your projects WEB-INF\bin\deployment\wasce.web.xml file. Uncomment the 'MyDatasource' resource-ref. 3. Re-deploy. Configuring Websphere Application Server Community Edition Database Connectivity Follow these steps to configure a sample datasource on WebSphere Application Server Community Edition (WAS CE). These instuctions are only needed when using a WAS CE that was not installed with WebSphere Portlet Factory 6.1.2. 1. Extract <INSTALLIMAGE>/config/EmployeeSampleDB.zip to <WASCE_ROOT>/var/derby 2. From a command console, change to the <WASCE_ROOT>/var/derby/sample directory 3. In command console enter: wasce-deploy-sample --user system --password manager 4. Check the wasce-datasource-results.txt for confirmation of datasource creation. 5. Edit your projects WEB-INF\bin\deployment\geronimo-web.xml file. Uncomment the EmployeeDatasource dependency and resource references.
6. Edit your projects WEB-INF\bin\deployment\wasce.web.xml file. Uncomment the 'MyDatasource' resource-ref. 7. Re-deploy. Configuring a sample datasource on WebSphere Application Server Follow these steps to configure a sample datasource on WebSphere Application Server. (Portlet Factory 6.1.2) 1. Extract <INSTALLIMAGE>/config/EmployeeSampleDB.zip to the AppServer \derby\databases directory. 2. Edit the was-datasource.bat file, changing the values of SOAP_CONNECTOR_ADDRESS, USERNAME, and PASSWORD to reflect the values for your server. 3. From a command console change to the AppServer\derby\databases directory. 4. Execute the was-datasource.bat file. 5. You do not need to redeploy your application to use the sample datasource on WAS. Instructions for Portlet Factory versions released prior to 6.1.2 Employee Sample Database Creation Follow these instructions only if you are using a version of Portlet Factory that was released before version 6.1.2. 1. Save the employeesample.sql file attached to the Creating a SQL Service with IBM Portlet Factory sample Wiki page to local temp directory. 2. Open a command prompt and navigate to <WASInstallDir>/AppServer/derby/bin/ embedded 3. Type "ij" at DOS command prompt in the above folder. The commands use an SQL like syntax, and are typically followed by a semicolon (";"). 4. To create new database, from the "ij" command prompt, type the following command. a. CONNECT '<name_of_new_db>;create=true'; (e.g. "CONNECT 'employeedata;create=true';") 5. To create the Tables and Data in the database type the following command. a. RUN 'c:\<localtempdir>\employeesample.sql'; The database will be created in the root directory of Derby ie. C:\<WASInstallDir>/ AppServer/Dery. Please take note of the location and name of your sample database these will be used when you configure the database for use in your WebSphere Application Server.
Manual Configuration of Database Connectivity To access the Durby sample database, a JDBC Provider and a J2EE Data Source must be configured in WAS. Follow the steps below to create these resources. These instructions are only needed if you are using a version of Portlet Factory prior to version 6.1.2 or would like to manually setup your JDBC Provider and J2EE Data Source manually. Create a JDBC Provider Follow these steps to create the JDBC Provider. If a suitable JDBC Provider for Derby already exists, you can skip this section. 1. Stop WebSphere Portal server if it is running. 2. Start WebSphere Application server if it is not running. 3. Open the WebSphere Administrative Console. 4. In the left pane, click Resources -> JDBC Providers. 5. Set the scope to a cell or node that includes both the server1 and WebSphere_Portal application server instances. 6. Click New to create a new provider. a. For Portal 6.0 only i. For the Database Type, select Derby. ii. For the Provider Type, select Derby JDBC Provider. iii. For the Implementation Type, select Connection pool data source. iv. Click Next. 7. Click Finish to accept these changes. 8. Click Save to save directly to master configuration. Create a J2EE Data Source Follow these steps to create the data source. If a suitable data source exists, you can skip this section. 1. Open the JDBC provider you created earlier. 2. Click Data Sources. 3. Click New to create a new data source. a. Enter a Name for the data source. b. Enter the JNDI Name used in the sample: jdbc/wpf_samples. Note: This sample uses this value as the default JNDI name. If you enter a different name here, you will have to edit the JNDI name in the samples.sql_service.sqlservicedatasource.pset Profile Set to match the name you enter here. c. For Portal 6.1 only i. Select (none) for Component-managed authentication alias and XA recovery authentication alias ii. Click Next
iii. Enter the path to where you saved the sample database into the Database Name field. i.e. ${was_install_root}/derby/ databases/employeesampledb/sample iv. Click Next. v. Click Finish. d. For Portal 6.0 only i. Click Specify a user-defined data store helper, ii. For the Data store helper classname, enter com.ibm.websphere.rsadapter.derbydatastorehelper. iii. Click WebSphere Application Server data source properties. iv. Set Statement Cache Size to 0. v. Click Finish to close these properties. e. Click OK to accept these changes. 4. For Portal 6.0 Only a. Add Custom Properties i. Open the new Data Source. ii. Click Custom Properties. In Portal 5.x, scroll to the bottom of the upper portlet to find this link. iii. Click New to add a custom property. 1. Name the property databasename. 2. Enter the full path to the sample Derby database folder. This folder is in the sample folder that you copied locally, i.e. C:\AppserveInstallDir\derby\EmployeeSampleDB \sample. 3. Click OK to add the new property. 5. Save the changes to the JDBC Provider and the J2EE Data Source. a. Click the Save link at the top of the page. b. Click the Save button to commit these changes. Test the new Data Source Follow these steps to test the data source. 1. Using the WebSphere Administrative console, test the connection to ensure that everything is configured correctly. a. In the left pane, click Resources -> JDBC Providers. b. Click the JDBC provider created earlier. c. Click the Data Sources link. d. Check the box to the left of the data source created earlier to indicate which data source to test. e. Click Test Connection. The message, Test connection for datasource <datasourcename> on server <servername> at node <NodeName> was successful. should display after a few seconds. 2. Shutdown WebSphere Application Server to release the earlier connection. 3. Restart WebSphere Portal Server to connect to the new data source. 4. Open and run the SqlEmployeeService model to confirm that the data source is working correctly.
Resources WebSphere Portlet Factory product documentation http://www.ibm.com/developerworks/websphere/zones/portal/portletfactory/proddoc.html WebSphere Portlet Factory support http://www.ibm.com/software/genservers/portletfactory/support/ developerworks forums http://www.ibm.com/developerworks/forums/wsdd_forums.jsp Trademarks DB2, IBM, Lotus, Tivoli, Rational, and WebSphere are trademarks or registered trademarks of IBM Corporation in the United States, other countries, or both. Windows and Windows NT are registered trademarks of Microsoft Corporation in the United States, other countries, or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Other company, product, and service names may be trademarks or service marks of others.