This chapter contains the following topics:
A JDBC driver is a software component that enables a Java application to interact with a database. Four types of JDBC drivers are available. Oracle JD Edwards EnterpriseOne supports Type 3 and Type 4 JDBC drivers.
This table provides an overview of each of the four types of JDBC drivers:
| JDBC Driver Type | Description |
|---|---|
| Type 1 JDBC driver | Type 1 JDBC drivers translate JDBC calls into ODBC calls. Type 1 JDBC drivers are usually called JDBC-ODBC bridge drivers. |
| Type 2 JDBC driver | Type 2 JDBC drivers translate JDBC calls into native DBMS APIs. The Type 2 drivers consist of a Java component and a native code component, which requires that binary code be loaded on each client machine. |
| Type 3 JDBC driver | Type 3 JDBC drivers are pure Java drivers that use database middleware. The Type 3 drivers communicate with the database through middleware servers that must be running in the network. The net protocol allows the client JDBC drivers to be very small and to load quickly. Fetching data rows may take longer because the data comes through a middleware server.
The JD Edwards EnterpriseOne Data Access Server (DAS) is a read-only Type 3 JDBC driver. The client is a small jar file that requires no configuration. The driver accesses the database through a DAS server. The DAS server is administered through Server Manager. |
| Type 4 JDBC driver | Type 4 JDBC drivers are pure Java drivers that access a database directly. The Type 4 drivers are sometimes called thin drivers. Type 4 JDBC drivers have relatively fast performance.
The JD Edwards EnterpriseOne Data Access Driver (DADriver) is a read-only type 4 JDBC driver. The DADriver client consists of many jar files and configuration files. The installation and administration is facilitated by Server Manager |
The JD Edwards EnterpriseOne JDBC drivers provide read-only access to JD Edwards EnterpriseOne application and product data. In addition to masking the details for the many supported databases and platforms that JD Edwards EnterpriseOne products support, the JDBC drivers encapsulate additional filtering and processing that must occur in order to preserve data and semantic integrity.
The JD Edwards EnterpriseOne JDBC drivers provide Java applications with a logical connection to JD Edwards EnterpriseOne data. Applications view this logical connection as a normal database connection, despite the fact that specific data source details are hidden. In some cases, the JDBC driver maps a single logical connection to multiple physical data sources. In a sense, the JDBC driver presents the set of data that JD Edwards EnterpriseOne products manage as a database.
Use a JD Edwards EnterpriseOne JDBC driver if you are developing or using software that requires or expects you to plug in a JDBC driver for data access, and you need to interact with JD Edwards EnterpriseOne application and product data.
If you are using a Type 3 JDBC driver, you must install JD Edwards EnterpriseOne Tools Release 8.98 or later Tools software version.
If you are using a Type 4 JDBC driver, you must install JD Edwards EnterpriseOne Tools Release 8.98.1 or later Tools software version.
If you are trying to read small amounts of data using an interoperability client over a network, use the Type 3 JDBC driver. This list provides some examples for using the Type 3 JDBC driver:
When using a commercial database middleware library (such as TopLink).
When using a commercial database visualization tool (such as DBVisualizer).
When retrieving JD Edwards EnterpriseOne data into a spreadsheet that has JDBC features (such as Excel).
The Type 3 driver can support approximately 1,000 desktops.
The JD Edwards EnterpriseOne product suite employs a diverse set of data sources. Specific filtering must occur for certain data sources while others can be used as is. The JD Edwards EnterpriseOne JDBC drivers define various connection modes that indicate the type of additional filtering and processing that the data requires. Application code designates the connection mode when it establishes new connections.
Currently the only connection mode supported is enterpriseone, which establishes a connection for reading JD Edwards EnterpriseOne enterprise resource planning (ERP) 9.0 data. This connection mode is implemented using JDBj, the Java class library that encapsulates most aspects of ERP data access middleware functionality such as object configuration management (OCM), ERP triggers, ERP business views, ERP row and column security, and decimal scrubbing.
The enterpriseone connection mode provides read-only access to ERP data. The concept of connection modes enables the extension of the JD Edwards EnterpriseOne JDBC drivers for other JD Edwards EnterpriseOne products as well.
Server Manager installs the components for both of the JD Edwards EnterpriseOne JDBC drivers.
See "Create a JD Edwards EnterpriseOne Data Access Server as a New Managed Instance” in the JD Edwards EnterpriseOne Tools Server Manager Guide on My Oracle Support.
See "Install a JD Edwards EnterpriseOne Data Access Driver" in the JD Edwards EnterpriseOne Tools Server Manager Guide on My Oracle Support.
Important:
If you are using a Type 3 JDBC driver, you must configure the JDBC driver by copying the e1jdbc.jar driver jar file to the class path of the application that will use the JDBC driver. The e1jdbc.jar jar file is located in the classes folder of the JD Edwards EnterpriseOne Data Access Server (DAS).The Type 4 JDBC driver does not require manual configuration.
Java code that uses a JDBC driver must register the driver class name and designate a connection URL and optional connection properties that collectively identify the data source that the JDBC driver is accessing.
You must register the JD Edwards EnterpriseOne JDBC driver class name with the JDBC Driver Manager before attempting to use the driver. You register the JD Edwards EnterpriseOne JDBC driver using Class.forName. The following table shows the Type 3 and Type 4 JDBC driver class names.
| JDBC Driver | Class Name |
|---|---|
| Type 3 JDBC Driver | com.jdedwards.jdbc.driver.Driver |
| Type 4 JDBC Driver | com.jdedwards.jdbc.driver.JDBCDriver |
The following table provides example registrations for the Type 3 and Type 4 JDBC drivers:
| JDBC Driver Type | Example Registration |
|---|---|
| Type 3 JDBC Driver | Class.forName(“com.jdedwards.jdbc.driver.Driver”) |
| Type 4 JDBC Driver | Class.forName(“com.jdedwards.jdbc.driver.JDBCDriver”) |
Some environments provide alternate mechanisms for registering JDBC drivers.
You must pass the following values to DriverManager.getConnection when establishing a JD Edwards EnterpriseOne JDBC connection:
Connection mode: enterpriseone.
Connection target: The ERP environment.
User name and password: The ERP user name and password.
The connection mode designates the type of JD Edwards EnterpriseOne product data that you plan to access.
The connection target, user name, and password depend on the connection mode.
The format for the connection URL is:
jdbc:oracle:connectionMode://<environment>
Note:
If you are using the Type 3 JDBC driver, include the host name and port number of the DAS server, for example:jdbc:oracle:connectionMode://hostname:port/<environment>The JD Edwards EnterpriseOne JDBC drivers recognize several connection properties that you can set when you establish a new connection. You specify these in the connection URL or in the java.util.Properties object that you pass to DriverManager.getConnection. If you specify the same property in both places, the value in the URL takes precedence.
If the property value contains one or more semicolons, you may need use parentheses to delimit the property value. Otherwise, parentheses are optional.
The following table shows the connection properties that the JD Edwards EnterpriseOne JDBC drivers recognize. The set of valid connection properties varies based on the connection mode. The JD Edwards EnterpriseOne JDBC drivers ignore any connection properties that are not listed in this table:
| Connection Mode | Property Name | Property Value |
|---|---|---|
| enterpriseone | enterpriseone.role | The ERP role, if any. The default is *ALL. This property value applies only if you are accessing ERP 9 or later data. |
| enterpriseone | impersonate | The user name, which will be substituted for authorization purposes at runtime in a proxy authentication mode.
This is discussed in the JDBC Security Considerations section. |
This example code shows how to connect to ERP environment ADEVHPO2I:
Connection connection = DriverManager.getConnection( "jdbc:oracle:enterpriseone://ADEVHPO2I;", "myuser", "mypassword");
Note:
If you are using a Type 3 driver, include the host name and port of the DAS server, for example: “jdbc:oracle:enterpriseone://hostname:port/ADEVHPO2I;”,JD Edwards EnterpriseOne JDBC drivers require a user name and password for authentication. At the same time, the same user name is authorized for the environment and role, which are passed in the connection URL. If you do not specify a role in the connection URL, the system uses *ALL. This model poses a serious security risk and a high maintenance requirement for third-party systems where a single JDBC connection is shared across multiple users.
To alleviate this problem, the JD Edwards EnterpriseOne JDBC drivers allow for a proxy authentication model by way of the impersonate connection property. In this model, the authentication and authorization are separated into two steps:
All users are authenticated through the security server with a sign-on EnterpriseOne proxy user name and password.
Important:
If you are using a Type 3 JDBC driver, this user name must be the same as the JDBj Bootstrap session user ID of the Data Access Server instance to which you are connecting.The impersonate user name that is passed in the connection property, is authorized for the environment and role. If you do not specify a role in the connection URL, the system uses *ALL.
The JD Edwards EnterpriseOne JDBC drivers support different flavors of SQL depending on the connection mode.
The JDBC drivers implement JD Edwards EnterpriseOne connection modes using JDBj, which is a Java data access API. The JDBC drivers parse SQL statements and transforms them into JDBj operations.
In general, the JDBC driver using the EnterpriseOne connection accepts only SELECT statements. All other operations, such as INSERT, UPDATE, DELETE, ALTER, DROP, and CREATE statements are not supported. If the driver cannot parse the SQL statement, then the JDBC driver throws an SQLException with a message that explains the parsing error.
The following table describes the SQL grammar that the parser recognizes. In this table, SQL keywords are in bold font (SELECT.) SQL keywords are not case sensitive. Rule names are listed in italics (where-clause.) Terminal symbols are noted. Optional clauses are listed in square brackets (,[ order-by-clause ].) Clauses that may repeat 0 or more times are listed in parenthesis followed by an asterisk (( , database-object-with-alias )*.) A vertical bar indicates that one of a set of options is valid (* | fields).
| Rule | Definition |
|---|---|
| select-statement | SELECT fields-clause FROM database-objects [ where-clause ] [group-by-clause ] [ order-by-clause ] |
| subquery-clause | SELECT fields-clause FROM database-object-with-alias [ where-clause ] [ group-by-clause ] |
| database-objects | database-object-with-alias ( , database-object-with-alias )* |
| database-object-with-alias | database-object [ ID ]
Note: ID is a terminal symbol. |
| database-object | ID
Note: ID is a terminal symbol. Database object names are table and business view names. Do not qualify these with an owner or schema. The JDBC driver uses its own data source resolution mechanisms (such as an ERP system's OCM) to resolve database object name qualifiers. However, if you require a schema to satisfy some third-party software requirements, you qualify the table or business view names with JDE as the schema. JD Edwards EnterpriseOne does not have a schema or catalog concept and this qualification is ignored at runtime. |
| fields-clause | *|fields| field-function-expressions |
| fields | field ( , field )* |field AS alias ( , field AS alias)* |
| field | database-object [ . ID [ . field-instance ]]
Note: ID is a terminal symbol. Field names are in the format database-object.field.instance, where database-object and instance are optional. Field names match data dictionary names rather than physical column names. For example, use AN8 (the data dictionary name for address book number) rather than ABAN8 (the physical F0101 column name). Instance is an integer that refers to the instance of a particular field when used in a self-join. |
| field-instance | INTEGER_LITERAL
Note: INTEGER_LITERAL is a terminal symbol. |
| field-function-expressions | field-function-expression ( , field-function-expression )* | field-function-expression AS alias( , field-function-expression AS alias )* |
| field-function-expression | type1-field-function-expression
| type2-field-function-expression | type3-field-function-expression |
| type1-field-function-expression | AVG|COUNT|SUM[DISTINCT] ( field )
Note: See the examples provided in the following table. |
| type2-field-function-expression | MIN|MAX ( field )
Note: See the examples provided in the following table. |
| type3-field-function-expression | COUNT ( * ) |
| field-reference | field |
| literals | literal ( , literals )* |
| literal | STRING_LITERAL
| INTEGER_LITERAL | FLOATING_POINT_LITERAL | NULL | ? Note: STRING_LITERAL, INTEGER_LITERAL, and FLOATING_POINT_LITERAL are terminal symbols. |
| where-clause | WHERE or-expression |
| group-by-clause | GROUP BY group-by-fields |
| order-by-clause | ORDER BY order-by-fields |
| order-by-fields | order-by-field-and-direction( , order-by-field-and-direction )* |
| order-by-field-and-direction | field-reference [ order-by-direction ] |
| order-by-direction | ASC | DESC |
| or-expression | and-expression ( OR and-expression )* |
| and-expression | not-expression ( AND not-expression )* |
| not-expression | [ NOT ] sub-expression |
| sub-expression | exists-clause
| relational-expression | (or-expression) |
| exists-clause | EXISTS ( subquery-clause ) |
| relational-expression | field field-expression | in-expression | between-expression | like-expression | is-null-expression
Note: Inconsistent results might occur if you use a field that requires decimal scrubbing within a relational expression. |
| field-expression | comparison-op ( ( [ ALL | ANY ] ( subquery-clause ) ) | element ) |
| in-expression | [ NOT ] IN(subquery-clause | elements ) |
| between-expression | [ NOT ] BETWEENelement AND element |
| like-expression | LIKE element |
| is-null-expression | IS [ NOT ] NULL |
| elements | element ( , element )* |
| element | field-reference | literal |
| comparison-op | = | != | <> | > | >= | < | <= | *= | =* | *=* |
The following are some examples of SQL statements that are allowed:
| Object Type | Statement |
|---|---|
| Table |
select AN8 from F0101 or select AN8 AS AddressBookNumber from F0101 |
| Select All Table |
select * from F0101 |
| Table Join |
select avg(t1.an8), min(t1.an8),max(t1.an8), count (t1.Name), sum(t1.an8), avg(distinct t1.an8), count (distinct t1.name),sum(distinct t1.an8),t1.an8 from F0101 to, F0010 t1 where t0.an8=t1.an8 group by t1.an8 |
| Table Union |
select F4211.KCOO, F4211.DOCO, F4211.DCTO , MAX (F4211.LNID), COUNT(F4211.DOCO), MIN(F4211.LNID), min (F4211.AN8) from F4211 group by F4211.LNID,F4211.DOCO, F4211.DCTO,F4211.KCOO UNION select F42119.KCOO, F42119.DOCO, F42119.DCTO , MAX(F42119.LNID), COUNT (F42119.DOCO), MIN(F42119.LNID), min(F42119.AN8) from F42119 group by F42119.LNID, F42119.DOCO, F42119.DCTO,F42119.KCOO order by F4211.DOCO DESC, F4211.KCOO asc |
| Single Table Business View |
select AN8 from V0101C |
| Multiple Table Business View |
select F0101.AN8, F0116.AN8 from V0101JE |
| Union Business View |
select max(F4211.KCOO), max(F4211.KCOO) from V4211A |
The JD Edwards EnterpriseOne JDBC drivers support different JDBC features depending on the connection mode. In general, the JDBC drivers implement the JDBC 3.0 specification as it is defined in Java 2 Platform Standard Edition version 5.0 (also called version 1.5.)
The JDBC driver enterpriseone connection mode explicitly does not support the following JDBC features:
Catalog methods (in DatabaseMetaData) with the exception of getCatalogs, getSchemas, getTables and getColumns.
Cursor names (Statement.setCursorName and ResultSet.getCursorName).
ResultSetMetaData as returned by PreparedStatement.getMetaData (the same information is available from ResultSet.getMetaData).
Result set holdability (Connection.createStatement, Connection.prepareStatement, Connection.prepareCall, and Statement.getResultSetHoldability).
Savepoints (Connection.setSavepoint and Connection.rollback).
Scrollable result sets (Connection.createStatement, Connection.prepareStatement, Connection.prepareCall, Statement.getResultSetType, and ResultSet.getType).
Stored procedures (Connection.prepareCall).
Type map (Connection.setTypeMap, Connection.getTypeMap, and ResultSet.getObject).
Update operations that involve JD Edwards EnterpriseOne software data (Statement.executeUpdate, PreparedStatement.executeUpdate, and ResultSet update methods).
In most cases, invoking these features results in an SQLException with a message describing the specific feature that is not supported.
When errors occur, the JDBC driver throws SQLExceptions. In your code, it is helpful to print or log these exceptions so that you can inspect or report them as part of the troubleshooting process. It is especially helpful to inspect entire exception stack traces, because traces include exception messages, class names, lines numbers, and cause exceptions that lead to SQLExceptions.
When you evaluate a series of exceptions in a trace, you should concentrate on the first exception because it is often the cause of subsequent exceptions.
Some example exceptions and their recovery are discussed here.
Exception: java.sql.SQLException: No suitable driver
Cause: The JD Edwards EnterpriseOne JDBC drivers use the native database JDBC drivers to access physical data. If the class path does not include the necessary drivers, then the JDBC drivers throw this exception on any attempt to read physical data.
Recovery: For the Type 3 JDBC driver, contact your system administrator and ensure that all of the applicable JDBC drivers are included in the Data Access Server's class path.
For the Type 4 JDBC driver, contact your system administrator and ensure that all of the applicable JDBC drivers are included in the same class path as the Data Access Driver.
Exception: com.jdedwards.services.objectlookup.DataSourceNotFoundException: Data source for F0010, TBLE not found. (with a cause message in parenthesis)
Cause: This exception indicates that the JDBC driver cannot access its system tables in ERP mode. Table F0010 is the first system table that the JDBC driver attempts to access. Be sure to check the cause message that is attached to the exception message. The exception trace usually includes a direct cause as well.
Recovery: Check the cause exception and follow the recovery instructions listed for those exceptions. If none apply, contact your system administrator and verify that the [JDBj-BOOTSTRAP DATA SOURCE] section of jdbj.ini file references a valid data source. The JDBj-BOOTSTRAP DATA SOURCE section describes the location for the ERP system tables, like F0010.
Exception: If you are using the Type 3 JDBC driver, you might receive an error message that indicates that table specifications do not exist.
Cause: This exception indicates that table specifications have not been generated for a particular table.
Recovery: To generate specifications for a table, sign-on to an HTML web client and run data browser for the table. When you use a Type 3 JDBC driver, you must run dataBrowser for any table that has not been previously opened from an HTM web client.
The following table provider terminology used in this chapter. These terms are not available in the glossary.
Connection mode is a term that applies only to the JDBC drivers and provides an indication of the type of additional filtering and processing that the JD Edwards EnterpriseOne data that you are accessing requires. Application code designates a connection mode when it establishes each new connection.
Properties that applications pass to the JDBC drivers when establishing a new connection in order to configure a particular connection type. The concept of connection properties is a standard JDBC mechanism, but each driver defines its own set of recognized connection properties.
A string that identifies a particular data source to which to connect. The concept of a connection URL is a standard JDBC mechanism, but each driver defines its own URL syntax.
A string that identifies the primary class for a JDBC driver. You must register this class name with the JDBC driver manager before using it. this is a standard JDBC concept, but each driver defines its own driver class name.
The JDBC class that manages multiple registered JDBC drivers and dispatches connection initialization requests to them. the Java driver manager class is java.sql.DriverManager.
Data that is managed within an ERP environment.
The Java class library that encapsulates most aspects of JD Edwards EnterpriseOne software data access middleware functionality such as OCM, ERP triggers, ERP business views, ERP row security, and decimal scrubbing.
The JDBC Type 3 driver is a network-protocol, all-Java driver. This style of driver translates JDBC calls into the middleware vendor's protocol, which is then translated to a DBMS protocol by a middleware server. The middleware provides connectivity to many different databases.
The JDBC Type 4 driver is a pure Java driver that accesses a database directly. Type 4 drivers are sometimes called thin drivers. Type 4 JDBC drivers have relatively fast performance.