Content Services for JDBC Driver User Guide

Transcription

1 Content Services for JDBC Driver User Guide Version 5.3 SP1 August 2005

2 Copyright EMC Corporation. All rights reserved

3 Table of Contents Preface... 7 Chapter 1 Introducing Content Services for JDBC Driver... 9 Content Services for JDBC Driver an overview... 9 The Docbase JDBC Service SCS JDBC Service Connection pooling Using data sources Chapter 2 Content Services for JDBC Driver Basics Overview SCS JDBC Service requirements Client library requirements functions The Content URL Importing required packages Registering Content Services for JDBC Driver Registering the Docbase JDBC Service Registering the SCS JDBC Service Connecting to a Docbase Specifying a Docbase URL, user name, and password Specifying a Docbase URL including the user name and password Specifying a Docbase URL and Properties object Connecting to a Site Caching Services repository Specifying a database URL, user name, and password Specifying a database URL including the user name and password Specifying a database URL and Properties object Using the dmjdbc.properties file Setting logging levels Creating a statement object Executing DQL queries with the Docbase JDBC Driver Executing SQL queries with the SCS JDBC Service Executing server API methods Closing ResultSet and Statement objects Making changes to the database Committing database changes Retrieving content files from a Docbase Retrieving content files from a Site Caching Services repository Closing the connection Content Services for JDBC Driver User Guide 3

4 Table of Contents Chapter 3 Using Data Sources, JNDI, and Connection Pooling Connecting with a data source Connecting without JNDI Connecting with a data source and JNDI Logging and tracing with a data source Connection pooling Loading JDBC Services Creating the connection pool Using the dmjdbcpool.properties file Obtaining a connection from the pool Returning connections to the pool Connection pooling in server-side applications Using connection pools in Servlets Configuring the WebSphere application server for JDBC Services Configuring to use the JDBC Driver directly Configuring to use DataSources directly Using Content Services for JDBC Driver with the WebSphere application server Appendix A JDBC APIs Appendix B Code Examples Generic JDBC Services code example Inserting, updating, and deleting records JSP code example Example servlet code Connection pooling servlet example Retrieving content files from a Docbase Retrieving content files from a Site Caching Services repository Content Services for JDBC Driver User Guide

5 Table of Contents List of Figures Figure 1 1. Content Services for JDBC Driver Content Services for JDBC Driver User Guide 5

6 Table of Contents List of Tables Table 2 1. Content file location relative to value of URL Table 2 2. connection properties Table 2 3. SCS JDBC Service connection properties Table A 1. JDBC core APIs and methods Table A 2. Table A 3. Table A 4. Table A 5. Table A 6. Table A 7. Table A 8. Table A 9. Table A 10. Table A 11. /unsupported Content Services for JDBC Driver for JDBC methods in java.sql.driver /usupported Content Services for JDBC Driver for JDBC methods in java.sql.connection /unsupported Content Services for JDBC Driver for JDBC methods in java.sql.statement /unsupported Content Services for JDBC Driver for JDBC methods in java.sql.preparedstatement /unsupported Content Services for JDBC Driver for JDBC methods in java.sql.resultset /unsupported Content Services for JDBC Driver for JDBC methods in java.sql.databasemetadata /unsupported Content Services for JDBC Driver for JDBC methods in java.sql.resultsetmetadata /unsupported Content Services for JDBC Driver for JDBC methods in javax.sql.datsource /unsupported Content Services for JDBC Driver for JDBC methods in javax.sql.pooledconnection /unsupported Content Services for JDBC Driver for JDBC methods in javax.sql.connectionpooldatasource Content Services for JDBC Driver User Guide

7 Preface This manual contains the information and instructions you need to use Content Services for JDBC Driver database using the Java Database Connectivity (JDBC) standard. Use Content Services for JDBC Driver to query a Documentum Docbase, perform operations on documents in the Docbase, or access a Documentum Site Caching Services (SCS) repository on your Web site. This manual provides information on using Content Services for JDBC Driver in the applications, servlets, and Java Server Pages (JSPs) that you develop. Intended audience This manual is intended primarily for developers who create servlets, JSPs, or client applications that use Content Services for JDBC Driver. Revision history The following changes have been made to this document. Revision date August 2005 Description Initial publication. Related documentation Users of this manual should have experience in programming in Java. Installation instructions for the Content Services for JDBC Drivers are in the Content Services for JDBC Driver Release Notes. For information on Documentum s server API methods and Document Query Language (DQL), refer to the following manuals: Documentum Content Server API Reference Manual Content Services for JDBC Driver User Guide 7

8 Preface Documentum Content Server DQL Reference Manual 8 Content Services for JDBC Driver User Guide

9 Chapter 1 Introducing Content Services for JDBC Driver This chapter introduces Content Services for JDBC Driver. The chapter discusses the following topics: Content Services for JDBC Driver an overview, page 9 The Docbase JDBC Service, page 10 SCS JDBC Service, page 11 Connection pooling, page 11 Using data sources, page 11 Content Services for JDBC Driver an overview Java Database Connectivity (JDBC) is an interface that allows you to access a database from Java client applications, Java Server Pages (JSPs), or servlets. Content Services for JDBC Drivers lets you connect to a Documentum Docbase or Site Caching Service repository, issue server API commands, perform DQL queries in the Docbase or SQL queries in a Site Caching Services repository, access the Docbase or repository s metadata, and retrieve content files from the Docbase or Site Caching Services repository. Content Services for JDBC Driver provides support for most of the standard JDBC APIs. (Refer to Appendix A, JDBC APIs, for complete information on, which APIs are supported.) You can also use the Java Naming and Directory Interface (JNDI) with Content Services for JDBC Driver, so that your applications can connect to the database using logical names rather than hard-coded database names. You can create and access a connection pool with Content Services for JDBC Driver. Content Services for JDBC Driver supports dynamic queries. Your client applications can use existing database access codes and still work correctly with the Docbase and the Site Caching Services repository. Content Services for JDBC Driver User Guide 9

10 Introducing Content Services for JDBC Driver Content Services for JDBC Driver translates JDBC API calls issued by Java applications, servlets, and JSPs into Documentum server API calls. Content Services for JDBC Driver provides both a Docbase JDBC Drvier and a Site Caching Services JDBC Driver. Figure 1 1, page 10 following, shows role of Content Services for JDBC Driver as an interface between JSPs, servlets, Enterprise Java Beans (EJBs), client applications, and Documentum products: Figure 1-1. Content Services for JDBC Driver The Docbase JDBC Service The Docbase JDBC Service implements the JDBC 2.0 API using Documentum s Document Query Language (DQL) instead of ANSI SQL. 10 Content Services for JDBC Driver User Guide

11 Introducing Content Services for JDBC Driver Note: The Docbase JDBC Service also implements the JDBC 3.0 API. However, this API is not supported by Documentum and will throw an SQL exception error. Only use the JDBC 2.0 API. The Docbase JDBC Service supports the SQL3 Blob datatype. It does not support the SQL3 Array, Clob, Ref, and Struct datatypes. You see SQLExceptions if you use JDBC methods that support features not included in DQL. SCS JDBC Service The Site Caching Services JDBC Service is a wrapper driver for database JDBC drivers. A wrapper driver allows your application to communicate with the JDBC drivers for Oracle, Sybase, and other database servers. The SCS JDBC Service supports all features provided by the database driver. Additionally, the SCS JDBC Service uses the SQL3 Blob data type to represent the content files and metadata in the Site Caching Services repository. Connection pooling Content Services for JDBC Driver allows you to create a connection pool for your applications. Connection pooling allows applications to use connections that exist in a pool rather than opening and closing new connections. This speeds up your applications, because new database connections do not have to be constantly created and destroyed. You can use connection pooling with either the SCS JDBC Service or the Docbase JDBC Service. Using data sources The Content Services for JDBC Driver implements the JDBC 2.0 extension API javax.sql. The extension API allows you to use data sources, which are general-purpose objects for specifying databases and other resources to application programs. Java Naming and Directory Interface (JNDI) lets applications find and access remote services and resources, as well as use logical names rather than vendor-specific syntax to access services. Note: The Docbase JDBC Service also implements the JDBC 3.0 API. However, this API is not supported by Documentum and will throw an SQL exception error. Only use the JDBC 2.0 API. Content Services for JDBC Driver User Guide 11

12 Introducing Content Services for JDBC Driver The Content Services for JDBC Driver uses a DocumentumDataSource class that implements the data source interface and provides properties to use when you specify a Docbase to which an application connects. With the Documentum data source enabled, you do not have to register the JDBC Services class name and you can use logical names for URLs and other properties. For full instructions on using the DocumentumDataSource class, refer to Chapter 3, Using Data Sources, JNDI, and Connection Pooling. 12 Content Services for JDBC Driver User Guide

13 Content Services for JDBC Driver Basics Chapter 2 This chapter contains information on the code that must be in your applications in order to use Content Services for JDBC Driver to access a Docbase or Site Caching Services repository. This chapter also tells you how to include DQL or SQL statements in your applications so that you can query a Docbase or Site Caching Services repository. This chapter discusses the following topics: Overview, page 14 Client library requirements, page 14 functions, page 15 The Content URL, page 15 Importing required packages, page 17 Registering Content Services for JDBC Driver, page 17 Connecting to a Docbase, page 18 Connecting to a Site Caching Services repository, page 20 Creating a statement object, page 24 Executing DQL queries with the Docbase JDBC Driver, page 24 Executing SQL queries with the SCS JDBC Service, page 25 Executing server API methods, page 26 Closing ResultSet and Statement objects, page 27 Making changes to the database, page 27 Committing database changes, page 28 Retrieving content files from a Docbase, page 28 Retrieving content files from a Site Caching Services repository, page 30 Closing the connection, page 30 Content Services for JDBC Driver User Guide 13

14 Content Services for JDBC Driver Basics Overview In order to connect to and query a Docbase or Site Caching Services repository, your Java applications must include code for the following tasks: Importing required packages Registering JDBC Services Opening connections to the Docbase or Site Caching Services repository Creating Statement objects Executing queries Returning ResultSet objects from queries Processing the result sets Closing the ResultSet and Statement objects Making changes to the database Committing database changes Closing the database connection Your applications must include information that is specific to Documentum for JDBC for importing packages, registering JDBC Services, and opening connections to the database. However, you use standard Java code for these and other tasks. SCS JDBC Service requirements The SCS JDBC Service is a wrapper driver. To use the SCS JDBC Service, you must have a valid JDBC driver for the database. Your clients must have sufficient privileges to use the database JDBC driver for database access, and the database JDBC driver must have a user name and password for access to the database. The SCS JDBC Service supports all functions supported by the database JDBC driver. Client library requirements The client s Java path must include the following libraries: dfc.jar This library provides the Documentum Foundation Classes library. dfcbase.jar This library provides the Documentum Foundation Classes library. libdmcl40.so 14 Content Services for JDBC Driver User Guide

15 Content Services for JDBC Driver Basics These libraries provide the Documentum Client Libraries API. j2ee.jar This includes the java and javax packages. log4j.jar This library is used by Documentum Foundation Classes to log any Documentum Foundation Classes specific warnings or errors. functions The Docbase JDBC Service and SCS JDBC Service support different functions. The Docbase JDBC Service supports these DQL functions: Scalar functions (UPPER, LOWER, SUBSTR) Aggregate functions (COUNT, MIN, MAX, AVG, SUM) Date functions (DATEDIFF, DATEADD, DATEFLOOR,DATETOSTRING) ID functions The SCS JDBC Service supports all functions supported by the database JDBC Services used in an installation. The Content URL JDBC Services allows you to access content files in a Site Caching Services repository or a Docbase. Site Caching Services publishes documents from the Docbase to the Web site host. When Site Caching Services publishes documents from the Docbase to the Web site host, it does two things:: Publishes the content file from the Docbase to the Web server host s file system The content file is placed on the file system in the target root directory, which is specified when a Web publishing configuration is created. Publishes the attributes associated with the content file to the database table specified in the Web publishing configuration The database table includes an attribute a_webc_url. This attribute contains a partial URL to the location of a given content file on the Web site host s file system. The a_webc_url is the path relative to the target root directory. (Refer to Site Caching Services User Guide for more information on the target root directory.) The target root directory and the a_webc_url for a given document combine to form the absolute path to the location of any content file on the Web server host s file system. Content Services for JDBC Driver User Guide 15

16 Content Services for JDBC Driver Basics If the directory specified by the target root directory is the document root of the HTTP server, the content file can be retrieved by issuing a URL. For example, the following table shows the relationship between the content file location on the file system and the value of a_webc_url. The table assumes that the /local/documentum/webcache_target directory is the target root directory. Table 2-1. Content le location relative to value of URL Content file location on file system \usr\local\documentum\webcache_ target\sports\sports1.htm \usr\local\documentum\webcache_ target\sports\sports2.htm \usr\local\documentum\webcache_ target\business\business1.htm Value of a_webc_url attribute in database table Sports/sports1.htm Sports/sports2.htm Business/business1.htm If the directory /usr/local/documentum is the document root of the HTTP server or the directory /usr/local/documentum/webcache_target is a virtual root "SCS_target" on the HTTP server, the content files can be accessed using the following URLs: htm Alternatively, the content files can be accessed using the following URLs: file:///usr/local/documentum/webcache_target/sports/sports1.htm file:///usr/local/documentum/webcache_target/sports/sports2.htm file:///usr/local/documentum/webcache_target/business/business1.htm Or the following URLs on Windows: file:\\c:\documentum\\webcache_target\\sports\\sports1.htm file:\\c:\documentum\\webcache_target\\sports\\sports2.htm file:\\c:\documentum\\webcache_target\\business\\business1.htm When the Site Caching Services JDBC driver executes a query against the Site Caching Services repository s database, it retrieves the content file by concatenating the contenturl and the a_webc_url. The contenturl is a value defined in the dmjdbc.properties file. For the above examples, the HTTP protocol would use the following contenturl: webcache_target/ If the Site Caching Services JDBC driver and the Site Caching Services target are on the same machine, you can use the file protocol: 16 Content Services for JDBC Driver User Guide

17 Content Services for JDBC Driver Basics file:///usr/local/documentum/webcache_target/ on UNIX You can define the contenturl in the dmjdbc.properties file in either way. Refer to Using the dmjdbc.properties file, page 23 for more information on the dmjdbc.properties file. Importing required packages Your client applications must include the following import statements, regardless of whether you are using the Docbase JDBC Service or the SCS JDBC Service: import java.sql.*; for standard JDBC packages import javax.sql.*; for optional JDBC packages To use the extended functionality provided by the Documentum drivers, include this import statement: import com.documentum.oca.jdbc.common.*; To use the Docbase JDBC Service, include this import statement: import com.documentum.oca.jdbc.jdbc20.*; To use the SCS JDBC Service, include this import statement: import com.documentum.oca.jdbc.webcache.*; To use JNDI services, include this import statement: import javax.naming.*; Registering Content Services for JDBC Driver Your applications must include code to register Content Services for JDBC Driver with the program. Register the driver only once. Use the static registerdriver() method of the JDBC DriverManager class to declare the driver name string. Registering the Docbase JDBC Service For the Docbase JDBC Service, the syntax is: DriverManager.registerDriver ( new com.documentum.oca.jdbc.jdbc20.djdbcdriver () ); Content Services for JDBC Driver User Guide 17

18 Content Services for JDBC Driver Basics Alternatively, for JDK-compliant Java Virtual Machines, you can use the forname() method of the java.lang.class class to load JDBC drivers directly: Class.forName ("com.documentum.oca.jdbc.jdbc20.djdbcdriver"); Registering the SCS JDBC Service For the SCS JDBC Service, the syntax for using the registerdriver() method is: DriverManager.registerDriver ( new com.documentum.oca.jdbc.webcache.djdbcdriver () ); Use the following syntax with the forname() method for the SCS JDBC Service: Class.forName ("com.documentum.oca.jdbc.webcache.djdbcdriver"); Connecting to a Docbase Use the static getconnection() method of the JDBC DriverManager class to create a Connection object and connect to the Docbase. You can use the Connection object throughout your code to pass connection information to the underlying database, for creating Statement objects, and retrieving metadata from the database. Inputs required to create the Connection objects are the user name, password, and connection string identifying the JDBC Services to use. When you use the Docbase JDBC Service, you must also provide the name of the Docbase to which you are connecting. Your application can open a connection to the Docbase with or without a data source. This section discusses how to connect to a Docbase without a data source. Refer to Chapter 3, Using Data Sources, JNDI, and Connection Pooling, for information on connecting to a data source. The Documentum Docbase JDBC Service does not support login timeouts. Calling the static DriverManager.setLoginTimeout() method does not have any effect on your application. In each of the following cases, the URLs are not case-sensitive, but the class names are. The getconnection() method can be used with three different signatures. The parameters of signatures are: Database URL, user name, and user password Database URL that includes the user name and user password Database URL and Properties object 18 Content Services for JDBC Driver User Guide

19 Content Services for JDBC Driver Basics The following sections shows you how to create connections with each of these signatures. Specifying a Docbase URL, user name, and password This getconnection() signature takes the URL, user name, and password as separate parameters: getconnection("url","user","password"); The URL should be in the form: jdbc:documentum:oca.docbase@database For example, the following connects a user called bob, whose password is cat, to a Docbase named dog using the Docbase JDBC Service: Connection conn = DriverManager.getConnection ("jdbc:documentum:oca:docbase@dog","bob","cat"); Specifying a Docbase URL including the user name and password This getconnection() signature includes the user name and password in the database URL: getconnection("url") For example, the following connects a user called bob, whose password is cat, to a database named dog, using the Docbase JDBC Service. The URL, which includes the user name and password, is the only parameter: Connection conn = DriverManager.getConnection("jdbc:documentum:oca: docbase:bob/cat@dog"); Specifying a Docbase URL and Properties object This getconnection() signature includes a URL and a Properties object. You must import the java.util.properties class in order to use a Properties object: import java.util.properties; The Properties object can specify user name and password as well as other information. getconnection("url",properties_object_name) The URL should be in the form: Content Services for JDBC Driver User Guide 19

20 Content Services for JDBC Driver Basics jdbc:documentum:oca.docbase The Properties object is an object of the standard Java Properties class. The Docbase JDBC Service supports the properties shown in Table 2 2, page 20. Table 2-2. connection properties Property Datatype Description user String The user name for connecting to the Docbase password String The password for connecting to the Docbase database String The connection string for the Docbase server String The Docbase host name (optional) For example, the following code uses the java.util.properties() and put() methods to create a Properties object called info, then incorporates the Properties object into the getconnection() method: //Import packages and register the driver. import java.sql.*; import javax.sql.*; import java.util.properties; import com.documentum.oca.jdbc.jdbc20.* DriverManager.registerDriver (new com.documentum.oca.jdbc.jdbc20.djdbcdriver()); //Specify the properties object. The user is called bob, // the password is cat, and the Docbase is dog. java.util.properties info = new java.util.properties(); info.put ("user", "bob"); info.put ("password", "cat"); info.put ("database", "dog"); //Specify the Connection object. Connection conn = DriverManager.getConnection("jdbc:documentum:oca:docbase", info); Connecting to a Site Caching Services repository Use the static getconnection() method of the JDBC DriverManager class to create a Connection object and connect to the Site Caching Services repository s underlying database. You can use the Connection object throughout your code to pass connection 20 Content Services for JDBC Driver User Guide

21 Content Services for JDBC Driver Basics information to the underlying database, for creating Statement objects, and retrieving metadata from the database. Inputs required to create the Connection objects are user name, password, and connection string identifying the JDBC Services to use. When you use the SCS JDBC service, you must also provide the name of the database to which you are connecting. Your application can open a connection to the database with or without a data source. This section discusses how to connect to a Docbase without a data source. Refer to Chapter 3, Using Data Sources, JNDI, and Connection Pooling, for information on connecting to a data source. In each of the following cases, the URLs are not case-sensitive, but the class names are. The getconnection() method can be used with three different signatures. The parameters of signatures are: Database URL, user name, and user password Database URL that includes the user name and user password Database URL and Properties object The SCS JDBC Service has its own URL format. This format allows the client to add the database JDBC driver class name and the database driver URL to the Site Caching Services URL string. For example, if the database JDBC driver is called websphere.jdbc.oci.driver, with a URL of jdbc:websphere:oracle, the SCS JDBC Service URL is: jdbc:documentum:oca:webcache@websphere.jdbc.oci.driver/jdbc:websphere:oracle Specifying a database URL, user name, and password Use the following format for the getconnection() method, where the URL, user name, and password takes the String datatype: getconnection("url","username","password"); The URL must have this format, where webcache contains the database JDBC driver class name and its URL other than the database name: jdbc:documentum:oca:webcache@database For example, the following code connects a user named bob whose password cat is to a database called oracle1, using the WebSphere JDBC driver: Connection conn = DriverManager.getConnection ("jdbc:documentum:oca:webcache@websphere.jdbc.oci.driver/jdbc:websphere: oci@oracle1, "bob", "cat"); Content Services for JDBC Driver User Guide 21

22 Content Services for JDBC Driver Basics Specifying a database URL including the user name and password Use the following format for the getconnection() method, where the URL takes the String datatype: getconnection("url"); The URL takes the format: jdbc:documentum:oca:webcache@database The database section of the URL must contain the database JDBC driver class name, the URL for the database JDBC driver, and the user name and password to acceess database: database_driver_class_name/database_url:username/password@database_name For example, this code connects a user called bob with password cat to a database called oracle1: Connection conn = DriverManager.getConnection ("jdbc:documentum:oca:webcache@websphere.jdbc.oci.driver/jdbc:websphere: oci:bob/cat@oracle1"); Specifying a database URL and Properties object Use the following syntax with the getconnection() method to use a Properties object: getconnection("url",properties_object_name); The URL takes the following form: jdbc:documentum:oca Use a Properties object to provide the input. For example, the following code creates a Properties object called info and then opens a connection for the user called bob with password cat to a database called oracle1: java.util.properties info = new java.util.properties(); info.put ("user", "bob"); info.put ("password", "cat"); info.put ("database", "oracle1"); info.put ("jdbc.driver", "websphere.jdbc.oci.driver"); info.put ("jdbc.url", "jdbc:websphere:oracle"); getconnection ("jdbc:documentum:oca:webcache", info); The SCS JDBC Service supports the connection properties shown in Table 2 3, page 23: 22 Content Services for JDBC Driver User Guide

23 Content Services for JDBC Driver Basics Table 2-3. SCS JDBC Service connection properties Property Datatype Description user String The user name for connecting to the Docbase password String The password for connecting to the Docbase database String The connection string for the Docbase jdbc.driver String The database JDBC driver name jdbc.url String The database JDBC driver URL Here is a longer code sample: //Import packages and register the driver. import java.sql.*; import javax.sql.*; import java.util.properties; import com.documentum.oca.jdbc.webcache.* DriverManager.registerDriver (new com.documentum.oca.jdbc.webcache.djdbcdriver()); //Specify the properties object. java.util.properties info = new java.util.properties(); info.put("user", "bob"); info.put ("password", "cat"); info.put ("database", "oracle1"); info.put ("jdbc.driver", "websphere.jdbc.oci.driver"); info.put ("jdbc.url", "jdbc:websphere:oracle"); //Specify the connection object. Connection conn = DriverManager.getConnection("jdbc:documentum:oca:webcache", info); Using the dmjdbc.properties le The dmjdbc.properties file allows you to set the driver name of the database JDBC driver for your installation s database, the URL for the database JDBC driver, and the contenturl that points to the Site Caching Services content repository on your Web server. For example: contenturl= jdbc.url=jdbc:oracle:thin:<user>/<password>@<hostname>:<port>:<sid> jdbc.driver=oracle.jdbc.driver.oracledriver This dmjdbc.properties file points to a contenturl on host eng076, and contains the driver name and driver URL for the Oracle JDBC driver. Content Services for JDBC Driver User Guide 23

24 Content Services for JDBC Driver Basics The jdbc.driver, jdbc.url and contenturl specified in the dmjdbc.properties can be alternatively specified in the Properties Object passed to the getconnection(..) method. Setting logging levels You can set logging levels in the dmjdbc.properties file. There are five logging levels, DEBUG, INFO, WARNING, ERROR, and FATAL. For performance reasons, we recommend setting the logging level to WARNING. If you encounter errors, set the logging level to DEBUG to record more information in the logs. Set the logging level as follows, where loglevel is one of the logging levels: documentum.jdbc.loglevel=loglevel The resulting logs are in the same directory as the dmjdbc.jar file. Creating a statement object After you connect to the Docbase and create your Connection object, you must create a Statement object. Use the createstatement() method of the JDBC Connection object to create the Statement object. For example, the following code creates a Statement object called stmt using the Connection object called conn from the code in the previous sections: Statement stmt=conn.createstatement(); Executing DQL queries with the Docbase JDBC Driver Use the executequery() method of the Statement object to perform a query. The executequery() method takes a DQL statement as input and returns a JDBC ResultSet object. For example, if a Statement object is called stmt, the following code executes a DQL query and creates a ResultSet object called rset: ResultSet rset = stmt.executequery ("select object_name from dm_document where r_creation_date='12/31/1999'"); The ResultSet object is populated with the object_name column of all objects of type dm_document where the r_creation_date is December 31, Content Services for JDBC Driver User Guide

25 Content Services for JDBC Driver Basics Use the next() method of the ResultSet object to iterate through each item retrieved by the query. To use the data in the result set, use the appropriate getjava_data_type() method. For example, the following code uses the getstring() method to retrieve all object_names from the ResultSet object called rset: while (more = rset.next()) { n++; System.out.println("Result" + n + ": " + rset.getstring("object_name")); } Executing SQL queries with the SCS JDBC Service Use the executequery() method of the Statement object to perform a query. The executequery() method takes a SQL statement as input and returns a JDBC ResultSet object. For example, the following code queries a SCS table PROPDB_T80000C01_S, creating a ResultSet object called rset: ResultSet rset = stmt.executequery ("select object_name from PROPDB_T80000C01_S where r_creation_date>to_date('12/31/1999','mm/dd/yyyy')"); The ResultSet object is populated with the object_name column of all objects where the r_creation_date is December 31, Use the next() method of the ResultSet object to iterate through each item retrieved by the query. To use the data in the result set, use the appropriate getjava_data_type() method. For example, the following code uses the getstring() method to retrieve all object_names from the ResultSet object rset: while (more = rset.next()) { n++; System.out.println("Result" + n + ": " + rset.getstring("object_name")); } Content Services for JDBC Driver User Guide 25

26 Content Services for JDBC Driver Basics Executing server API methods Use the CallableStatement interface to execute server API methods with the Docbase JDBC Service. The server API methods associated with the server API functions dmapiget, dmapiexec, and dmapiset are supported in the JDBC Services. For more information about these functions, refer to Documentum Content Server Fundamentals and the Documentum Content Server Object Reference Manual. For more information about server API methods, refer to the Documentum Content Server API Reference Manual. When you issue a server API command, the results are returned as a ResultSet object. For methods using the dmapiget and dmapiexec functions, use the following syntax: {? = call apicommand (arg1,arg2,'...',argn)} For methods using the dmapiset function, use the following syntax: {? = call apicommand (arg1,arg2,'...',argn) value} For example, to get the creation date of an object: {? = call get ( e000021,r_creation_date,dd-mon-yy)}; To set a router s plan_end_date attribute to June 4, 2001: {? = call set ( e000021,plan_end_date,dd/mm/yy) 04/06/01} Your client application must use the JDBC CallableStatement? syntax to set the datatype for data returned by these commands. For example, to set the return type to the Java String type: call.registeroutparameter(1,types.varchar); The following code sample gets the creation date of an object, inserts the author name, and saves the inserted value: // Get the creation date. CallableStatement call = con.preparecall("{? = call get ( ec2e8,?, dd-mon-yy)}"); call.registeroutparameter(1, Types.VARCHAR); call.setstring(2, "r_creation_date"); call.execute(); String date = call.getstring(1); System.out.println("Creation Date = " + date); // Insert author. call = con.preparecall("{? = call insert ( ec2e8,authors[1]) Haden Fox}"); call.registeroutparameter(1, Types.BIT); call.execute(); Boolean b = call.getboolean(1); Boolean bb = new Boolean(b); System.out.println("API set = " + bb.tostring()); // Save the insert value. call = con.preparecall("{? = call save ( ec2e8}"); 26 Content Services for JDBC Driver User Guide

27 Content Services for JDBC Driver Basics call.registeroutparameter(1, Types.BIT); call.execute(); b = call.getboolean(1); bb = new Boolean(b); System.out.println("API save = " + bb.tostring()); call.close(); con.close(); Closing ResultSet and Statement objects Your code must use the close() method to close any ResultSet and Statement objects after the application processes them. If you do not explicitly close ResultSet and Statement objects, memory leaks can occur. Closing ResultSet and Statement objects also releases cursors in the database and reduces the risk of running out of cursors. For example, for a ResultSet object called rset and a Statement object called stmt, use the following syntax to close the objects: rset.close(); stmt.close(); When you close a Statement object created by a particular Connection object, the connection remains open. Making changes to the database Use standard JDBC syntax and APIs to make changes to the database. To do this, create a PreparedStatement object using the preparedstatement() method. You can then use the setmethod_name() methods on the PreparedStatement object in order to bind data into the prepared statement and send it to the database. For example, the following syntax uses a PreparedStatement object called pstmt to execute INSERT operations that add two rows to the dm_document table: // Prepare to insert new names in the table. PreparedStatement pstmt = conn.preparestatement ("insert into dm_document (object_name, subject) values (?,?)"); // Add JdbcTest1 as object name and cake1 as subject. pstmt.setstring(1, "JdbcTest1");// The first? is for object_name. pstmt.setstring(2, "cake1");// The second? is for subject. // Insert the row. pstmt.execute(); // Add JdbcTest2 as object name and cake2 as subject. pstmt.setstring(1, "JdbcTest2");// The first? is for object_name. pstmt.setstring(2, "cake2");// The second? is for subject. Content Services for JDBC Driver User Guide 27

28 Content Services for JDBC Driver Basics // Insert the row. pstmt.executeupdate(); // Close the statement. pstmt.close(); Site Caching Services repositories are located on Web sites, and the documents in them are modified in the originating Docbase rather than on the Web site. Therefore, we recommend that you do not directly modify the Site Caching Services repository s database or the content files located in the repository. Committing database changes By default, database operations such as INSERT, UPDATE, and DELETE are committed automatically upon execution (auto-commit mode). You can disable auto-commit mode by setting it to FALSE. For example, the following code calls the setautocommit() method on a Connection object called conn: conn.setautocommit(false); If you set auto-commit to FALSE, you must then ma nually commit database changes: conn.commit(); You must also manually roll back any database change: conn.rollback(); Retrieving content les from a Docbase You can retrieve content files from a Docbase in two ways: To retrieve only primary renditions, use the command getblob( _content ) after locating the content file by referencing the corresponding object attributes in the Docbase. You can then use the Getfile API and CallableStatement interface to retrieve nonprimary renditions. For a complete code sample using getblob( _content ), refer to Retrieving content files from a Docbase, page 90. To retrieve primary or nonprimary renditions, use the Blob interface. The following code uses the first method. It obtains the object ID of a document called test.txt and then uses the object ID to retrieve the nonprimary PDF rendition of test.txt: //Get object ID. select r_object_id from dm_document where object_name='test.txt' 28 Content Services for JDBC Driver User Guide

29 Content Services for JDBC Driver Basics //Use Getfile API to retrieve nonprimary PDF rendition. String filename="c:\\temp\\tempfile.pdf"; CallableStatement cs = con.preparecall("{? = call getfile(?,?,pdf,0)}"); cs.registeroutparameter(1, Types.VARCHAR); cs.setstring(2, r_object_id); cs.setstring(3, filename); cs.execute() ; The following examples use the Blob interface to retrieve both primary and nonprimary renditions of documents in the Docbase. The ResultSet interface of JDBC Services allows you to pass the format of the document as an argument to the getblob method. For example, you can use following code to retrieve nonprimary renditions: String format = format; Blob b = rs.getblob(format) ; InputStream is = b.getbinarystream(); If the format were specified as pdf, the syntax would be: String format = pdf; Blob b = rs.getblob(pdf) ; InputStream is = b.getbinarystream(); For example, the following code retrieves both the primary rendition of a document, in text format, and a nonprimary PDF rendition: // After issuing DQL query and obtaining resultset while ( rs.next() ) { Blob b1 = rs.getblob("_content"); // Primary 'txt' rendition to be retrieved InputStream is1 = b1.getbinarystream() ; // Process InputStream is1 Blob b2 = rs.getblob("pdf"); // Non-primary 'pdf' rendition to be retrieved InputStream is2 = b2.getbinarystream(); // Process InputStream is2 } You can also retrieve the contents of a given format as a particular page by passing the format and the page number as arguments to the getblob method: String format="format"; int page = 0; Blob b = rs.getblob(format, page); InputStream is = b.getbinarystream(); You can pass the page number to the older version of the syntax as well: rs.getblob("_content", int page) Content Services for JDBC Driver User Guide 29

30 Content Services for JDBC Driver Basics Retrieving content les from a Site Caching Services repository Use the getblob( _content ) command to retrieve content files from a Site Caching Services repository. For example: Blob blob = rs.getblob("_content"); InputStream contents = blob.getbinarystream(); Once the content file is retrieved, use the common Java InputStream functions for manipulating or displaying the content file. The content file s location is a URL composed of the repository host s URL (called the base URL) plus the path to the content file (called the local URL). For example, the base URL might be and the local URL might be /buzz/news/pr2000/widgets html. The local URL is stored in the database as the a_webc_url attribute of the propdb_id_s and propdb_id_r tables. The base URL should be stored in the default database JDBC driver properties file by JDBC driver administrator. Use one of these three formats: contenturl= contenturl= contenturl=file://localhost/c: For complete sample code, refer to Retrieving content files from a Site Caching Services repository, page 91. Closing the connection You must close the database connection when your work is finished. For a Connection object called conn, the syntax is: conn.close(); 30 Content Services for JDBC Driver User Guide

31 Using Data Sources, JNDI, and Connection Pooling Chapter 3 Using Content Services for JDBC Driver, you can connect to the Docbase or Site Caching Services repository using data sources, which are general-purpose objects for specifying databases and other resources to application programs. Using data sources minimize the amount of database-specific code you must write in your applications, thereby reducing code maintenance and allowing greater code portability. Data sources also allow you to use the Java Naming and Directory Interface (JNDI). JNDI lets applications find and access remote services and resources, and use logical names rather than vendor-specific syntax to access services. You can use JDBC Services to create and access a connection pool. A connection pool consists of a pool of reusable Docbase connections. Connection pooling allows the reuse of connections, reduces the demands on you hardware, and allows your applications faster access to the database. This chapter discusses the following topics: Connecting with a data source, page 31 Logging and tracing with a data source, page 33 Connection pooling, page 34 Configuring the WebSphere application server for JDBC Services, page 38 Using Content Services for JDBC Driver with the WebSphere application server, page 45 Connecting with a data source You can connect to a Docbase using a data source with or without JNDI. In either case, your code must create an instance of the DocumentumDataSource class, initialize the connection properties of the DocumentumDataSource instance, and create a connection instance. Content Services for JDBC Driver User Guide 31

32 Using Data Sources, JNDI, and Connection Pooling Connecting without JNDI This code creates a DocumentumDataSource called dds and sets the ServerName, DatabaseName, User, and Password properties of the data source: DocumentumDataSource dds = new DocumentumDataSource(); dds.setservername("domain"); dds.setdatabasename("docbase"); dds.setuser("username"); dds.setpassword("password"); Connection conn = dds.getconnection(); You must include the server host name and Docbase name, as well as the user name and password to be used for connecting to the database. This code allows you to incorporate the user name and password in the getconnection() method and override the user name and password in the DocumentumDataSource instance: // optionally override the user name and password: Connection conn = dds.getconnection("username, "password"); Connecting with a data source and JNDI You can connect to the Docbase using a data source and JNDI. This minimizes the amount of vendor-specific code in your applications and allows you to use logical names instead. Only the code that binds a data source instance to a JNDI logical name needs to contain vendor-specific, hard-coded property settings. To connect using a data source and JNDI, you must import the correct packages, initialize the connection properties, register the data source with JNDI, and open the connection. First, import the required packages: import javax.naming.*; Next, create a DocumentumDataSource instance and initialize its connection properties. For example, this code creates a DocumentumDataSource instance called dds: DocumentumDataSource dds = new DocumentumDataSource(); dds.setservername("domain"); dds.setdatabasename("docbase"); dds.setuser("username"); dds.setpassword("password"); Then, register the data source instance with JNDI. The following example registers the data source instance with the WebSphere Application Server, which is providing the JNDI services: Context ctx = null; // Get JNDI services provider's environment. 32 Content Services for JDBC Driver User Guide

33 Using Data Sources, JNDI, and Connection Pooling Hashtable env = new Hashtable(); env.put(context.initial_context_factory, "websphere.jndi.wlinitialcontextfactory"); env.put(context.provider_url, "t3://localhost:7001"); // Bind Data Source with WebSphere Server. ctx = new InitialContext(env); ctx.bind("jdbc/documentum/oca", dds); At any point in your application following the ctx.bind() call, you can use the logical name jdbc/documentum/oca to open a connection to the Docbase described by the properties of the DocumentumDataSource instance dds. Last, use the logical name jdbc/documentum/oca to perform a lookup and open a connection to the Docbase: Connection conn = null; DocumentumDataSource dds = (DocumentumDataSource)ctx.lookup("jdbc/documentum/oca"); conn = dds.getconnection(); Logging and tracing with a data source When you create a data source instance, logging and tracing capabilities are disabled by default. You enable logging and tracing in an application by registering a character stream that JDBC uses to output logging and tracing information. A character stream records logging and tracing information for a specific data source instance. If you have multiple data source instances, you must register the character stream with each data source instance. The DriverManager class maintains its own character stream for logging and tracing information. Logging and tracing information written to a log stream registered to a data source instance is not written to the DriverManager class s character stream. The DocumentumDataSource class uses the following standard data source methods for logging and tracing: public synchronized void setlogwriter(printwriter pw) public synchronized PrintWriter getlogwriter() When you obtain a DocumentumDataSource instance from a JNDI name lookup, the DocumentumDataSource s PrintWriter is not set, even if PrintWriter was set when a data source instance was first bound to the JNDI name. Content Services for JDBC Driver User Guide 33

34 Using Data Sources, JNDI, and Connection Pooling Connection pooling Use connection pooling to create a pool of reusable database connections for your applications. Connection pooling services are provided by the application server you use. JDBC Services provides support for the connection pooling features of your application server. You can use connection pooling with or without JNDI. The pool grows dynamically based on the number of required connections. JDBC Services can automatically refresh configurations that are stale because of database errors. JDBC Services can be configured to automatically close connections that have been idle for too long. JDBC Services logs a stack trace of where idle connections were opened. JDBC Services blocks threads until a pooled connection is available. You can implement JDBC Services by changing the driver class and URL of a non-connection pooling JDBC driver. JDBC Services can be used in connection pooling with different application servers. Connection pooling is configured differently by each specific application server. Refer to Using Content Services for JDBC Driver with the WebSphere application server, page 45 for information on connection pooling with the IBM WebSphere Application Server. Loading JDBC Services JDBC Services automatically registers itself with the JDBC DriverManager class when DriverManager loads the JDBCConnectionPoolDriver class. The connection pool driver keeps a list of pools as a static variable, so you may want to do one of the following: You can keep a reference to an instance of the JdbcConnectionPoolDriver class where the garbage collector won t reclaim it. You can run Java with the -noclassgc flag. Use the following code to load the driver: Class.forName("com.Documentum.jdbc.pool.JdbcConnectionPoolDriver"); Import the correct classes: import com.documentum.oca.jdbc.pool.*; import com.documentum.oca.servlet.*; 34 Content Services for JDBC Driver User Guide

35 Using Data Sources, JNDI, and Connection Pooling Creating the connection pool When you create a new connection pool, you must name it and assign a number of initialization parameters. Once you create the pool, it is automatically registered with the pool driver, and you can start opening connections with it immediately. For example: // Initialization parameters are kept in a hash table. Hashtable args = new Hashtable(); // Call the underlying driver -- in this case, the Docbase driver. args.put("jdbc.driver", "com.documentum.oca.jdbc.jdbc20.djdbcdriver"); // The URL to connect the underlyng driver with the server. args.put("jdbc.url", "jdbc:documentum:oca:docbase"); // These are properties that get passed to DriverManager.getConnection(...). Properties jdbcproperties = new Properties(); jdbcproperties.put("username", "user_name"); jdbcproperties.put("password", "User_password"); jdbcproperties.put("database", "Docbase_name"); args.put("jdbc.properties", jdbcproperties); // The initial size of the pool. args.put("pool.initialsize", new Integer(initial_size)); // The maximum size to which the pool. args.put("pool.maxsize", new Integer(maximum_size)); // Each time the pool grows, it grows by the number of connections indicated. args.put("pool.growblock", new Integer(pool_growth)); // Wait time between connections, in milliseconds. args.put("pool.createwaittime", new Integer(creation_interval)); // Create the pool. JdbcConnectionPool dctmpool = new JdbcConnectionPool("dctmPool", args); Specify the parameters initial_size, maximum_size, and so on in the dmjdbcpool.properties file. Using the dmjdbcpool.properties le The dmjdbcpool.properties file contains parameters to be set for using connection pooling with JDBC Services. The file shipped in the tar file contains the necessaries entries. Specify the pooling-related properties in this properties file. Obtaining a connection from the pool After you create a connection pool, your applications must obtain a connection from the pool. For example, if your connection pool is called MyConnectionPool: String url = "jdbc:documentum:oca:pool"; Connection c = DriverManager.getConnection(jdbc:documentum:oca:pool:MyConnectionPool); Content Services for JDBC Driver User Guide 35