Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673285
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/compliance.adoc ---
@@ -0,0 +1,386 @@
+////
+/**
+ *@@@ START COPYRIGHT @@@
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * @@@ END COPYRIGHT @@@
+ */
+////
+
+[[type-4-driver-compliance]]
+= Type 4 Driver Compliance
+
+[[compliance-overview]]
+== Compliance Overview
+
+The Type 4 driver conforms where applicable to the JDBC
+3.0 API specification. However, this driver differs from the JDBC
+standard in some ways. This subsection describes the JDBC methods that
+are not supported, the methods and features that deviate from the
+specification, and features that are {project-name} extensions to the JDBC
standard.
+JDBC features that conform to the specification are not described in this
subsection.
+
+In addition, this chapter lists features of {project-name} SQL that are
not supported by the {project-name} JDBC Type 4 driver, other
+unsupported features, and restrictions.
+
+[[unsupported-features]]
+== Unsupported Features
+
+These methods in the java.sql package throw an SQLException with the
+message `Unsupported feature - <method-name>`:
+
+[cols="65%,35%", options="header"]
+|===
+| Method | Comments
+| `CallableStatement.getArray(int parameterIndex)` +
+`CallableStatement.getArray(String parameterName)` +
+`CallableStatement.getBlob(int parameterIndex)` +
+`CallableStatement.getBlob(String parameterName)` +
+`CallableStatement.getClob(int parameterIndex)` +
+`CallableStatement.getClob(String parameterName)` +
+`CallableStatement.getObject(int parameterIndex, Map map)` +
+`CallableStatement.getObject(String parameterName, Map map)` +
+`CallableStatement.getRef(int parameterIndex)` +
+`CallableStatement.getRef(String parameterName)` +
+`CallableStatement.getURL(int parameterIndex)` +
+`CallableStatement.getURL(String parameterName)` +
+`CallableStatement.executeBatch()` | The particular `CallableStatement`
method is not supported.
+| `Connection.releaseSavepoint(Savepoint savepoint)` +
+`Connection.rollback(Savepoint savepoint)` +
+`Connection.setSavepoint()` +
+`Connection.setSavepoint(String name)` | The particular `Connection`
methods are not supported.
+| `PreparedStatement.setArray(int parameterIndex, Array x)` +
+`PreparedStatement.setRef(int parameterIndex, Ref x)` +
+`PreparedStatement.setURL(int parameterIndex, URL x)` | The particular
`PreparedStatement` methods are not supported.
+| `ResultSet.getArray(int columnIndex)` +
+`ResultSet.getArray(String columnName)` +
+`ResultSet.getObject(int columnIndex, Map map)` +
+`ResultSet.getObject(String columnName, Map map)` +
+`ResultSet.getRef(int columnIndex)ResultSet.getRef(String columnName)` +
+`ResultSet.getURL(int columnIndex)` +
+`ResultSet.getURL(String columnName)` +
+`ResultSet.updateArray(int columnIndex)` +
+`ResultSet.updateArray(String columnName)` +
+`ResultSet.updateRef(int columnIndex)` +
+`ResultSet.updateRef(String columnName) | The particular `ResultSet`
methods are not supported.
+| `Statement.getQueryTimeout()` +
+`Statement.setQueryTimeout()` | The particular `Statement` methods are not
supported.
+|===
+
+The following methods in the java.sql package throw an SQLException with
+the message `Auto generated keys not supported`:
+
+[cols="65%,35%", options="header" ]
+|===
+| Method | Comments
+| `Connection.prepareStatement(String sql, int autoGeneratedKeys)` +
+`Connection.prepareStatement(String sql, int[] columnIndexes)` +
+`Connection.prepareStatement(String sql, String[] columnNames)` |
Automatically generated keys are not supported.
+| `Statement.executeUpdate(String sql, int autoGeneratedKeys)` +
+`Statement.executeUpdate(String sql, int[] columnIndexes)` +
+`Statement.executeUpdate(String sql, String[] columnNames)` +
+`Statement.getGeneratedKeys()` | Automatically generated keys are not
supported.
+|===
+
+The following methods in the java.sql package throw an SQLException with
+the message `Data type not supported`:
+
+[cols="65%,35%", options="header" ]
+|===
+| Method | Comments
+| `CallableStatement.getBytes(int parameterIndex)` +
+`CallableStatement.setBytes(String parameterIndex, bytes[] x)` | The
particular data type is not supported.
+|===
+
+The following interfaces in the `java.sql` package are not implemented in
+the Type 4 driver:
+
+[cols="65%,35%", options="header" ]
+|===
+| Method | Comments
+| `java.sql.Array` +
+`java.sql.Ref` +
+`java.sql.Savepoint` +
+`java.sql.SQLData` +
+`java.sql.SQLInput` +
+`java.sql.SQLOutput` +
+`java.sql.Struct` | The underlying data types are not supported by
{project-name}.
+|===
+
+<<<<
+The following interfaces in the `javax.sql` package are not implemented in
the Type 4 driver:
+
+[cols="65%,35%", options="header" ]
+|===
+| Method | Comments
+| `javax.sql.XAConnection` +
+`javax.sql.XADataSource` | Distributed Transactions, as described in the
JDBC 3.0 API specification, are not yet implemented.
+|===
+
+For additional information about deviations for some methods, see
<<deviations, Deviations>>.
+
+[[deviations]]
+== Deviations
+
+The following table lists methods that differ in execution from the JDBC
+specification. When an argument in a method is ignored, the Type 4
+driver does not throw an SQLException,thus allowing the application to
+continue processing. The application might not obtain the expected
+results, however. Other methods listed do not necessarily throw an
+SQLException, unless otherwise stated, although they differ from the
+specification.
+
+NOTE: The `java.sql.DatabaseMetaData.getVersionColumns()` method mimics the
+`java.sql.DatabaseMetaData.getBestRowIdentifier()` method because
+{project-name} SQL does not support `SQL_ROWVER` (a columns function that
+returns the column or columns in the specified table, if any, that are
+automatically updated by the data source when any value in the row is
+updated by any transaction).
+
+[cols="50%,50%", options="header" ]
+|===
+| Method | Comments
+| `java.sql.DatabaseMetaData.getColumns(String catalog, String
schemaPattern, String tableNamePattern, String columnNamePattern)` |
+The column is added to the column data, but its value is set to NULL
because {project-name} SQL does not support the column type for these types: +
+ +
+`SCOPE_CATALOG,` +
+`SCOPE_SCHEMA,` +
+`SCOPE_TABLE,` +
+and `SOURCE_DATA_TYPE`
+| `java.sql.DatabaseMetaData.getTables(String catalog, String
schemaPattern, String[] types)` |
+The column is added to the column data, but its value is set to NULL
because {project-name} SQL does not support the column type for these types: +
+ +
+`TYPE_CAT,` +
+`TYPE_SCHEMA,` +
+`TYPE_NAME,` +
+`SELF_REFERENCING_COL_NAME,` +
+and `REF_GENERATION.`
+| `java.sql.DatabaseMetaData.getUDTs(String catalog, String schemaPattern,
String tableNamePattern, int[] types)` |
+BASE_TYPE is added to the column data, but its value is set to NULL
because {project-name} SQL does not support the base type.
+| `java.sql.DatabaseMetaData.getVersionColumns()` |
+Mimics the `DatabaseMetaData.getBestRowIdentifier()` method because
{project-name} SQL does not support `SQL_ROWVER` (a columns function that
returns the
+column or columns in the specified table, if any, that are automatically
updated by the data source when any value in the row is updated by any
transaction).
+| `java.sql.Connection.createStatement(. . .)` +
+`java.sql.Connection.prepareStatement(. . .)` |
+The Type 4 driver does not support the scroll-sensitive result set type,
so an SQL Warning is issued if an application requests that type. The result
set is changed to
+a scroll-insensitive type.
+| `java.sql.ResultSet.setFetchDirection(. . .)` | The fetch direction
attribute is ignored.
+| `java.sql.Statement.cancel()` |
+In some instances, drops the connection to the server instead of just
canceling the query. You must then reconnect to the server.
+Note that the connection is dropped if `cancel()` is issued for a
statement that is being processed. Otherwise the connection is maintained.
+| `java.sql.Statement.setEscapeProcessing(. . .)` | Because {project-name}
SQL parses the escape syntax, disabling escape processing has no effect.
+| `java.sql.Statement.setFetchDirection(. . .)` | The fetch direction
attribute is ignored.
+|===
+
+<<<
+[[project-name-extensions]]
+== {project-name} Extensions
+
+The {project-name} extensions to the JDBC standard implemented in the Type
4 driver are as follows.
+
+[[internationalization-of-messages]]
+=== Internationalization of Messages
+
+The Type 4 driver is designed so that Java messages can be adopted for
+various languages. The error messages are stored outside the source code
+in a separate property file and retrieved dynamically based on the
+locale setting. The error messages in different languages are stored in
+separate property files based on the language and country. This
+extension does not apply to all messages that can occur when running
+JDBC applications.
+
+For details, see <<localizing-error-messages-and-status-messages,
Localizing Error Messages and Status Messages>>.
+
+[[additional-databasemetadata-apis]]
+=== Additional DatabaseMetaData APIs
+
+APIs added to the `HPT4DatabaseMetaData` class provide these capabilities:
+
+* Get a description of a table's synonyms.
++
+[source, java]
+----
+public java.sql.ResultSet getSynonymInfo(String catalog, String schema,
String table) throws SQLException
+----
+
+////
+* Get a description of a table's materialized views.
++
+[source, java]
+----
+public java.sql.ResultSet getMaterializedViewInfo(String catalog, String
schema, String table) throws SQLException
+----
+////
+
+[[additional-connection-apis]]
+=== Additional Connection APIs
+
+APIs added to the `HPT4Connection` class provide these capabilities:
+
+* Sets the current service name for this Connection object.
++
+[source, java]
+----
+public void setServiceName(String serviceName) throws SQLException
+----
+
+* Gets (retrieves) the current service name of this Connection object.
Default return value: HP_DEFAULT_SERVICE.
++
+[source, java]
+----
+public String getServiceName() throws SQLException
+----
+
+[[conformance-of-databasemetadata-methods-handling-of-null-parameters]]
+== Conformance of DatabaseMetaData Methods' Handling of Null Parameters
+
+This topic describes how the Type 4 driver determines the value of null
+parameters passed as a parameter value on DatabaseMetaData methods.
+Since other vendors might implement the JDBC specification differently,
+this information explains the Type 4 driver results on the affected
+queries.
+
+This implementation applies to methods that take parameters that can
+represent a pattern. The names of these parameters have the format:
+
+```
+attributePattern
+```
+
+The many methods of the java.sql.DatabaseMetaData class are affected;
+for example, the `getColumns()` method.
+
+For another example, schema is the attribute in the parameter
+`schemaPattern`, which is a parameter to the
`java.sql.ResultSet.getAttributes` method.
+
+[source, java]
+----
+public ResultSet getAttributes( String catalog
+ , String schemaPattern
+ , String typeNamePattern
+ , String attributeNamePattern
+ ) throws SQLException
+----
+
+If the application passes a null value, the null is treated as follows:
+
+* If a parameter name contains the suffix Pattern, the null is interpreted
as a `%` wild card.
+* If the parameter name does not contain the suffix `Pattern`, nulls are
interpreted as the default value for that parameter.
+
+Using this example, null parameters are interpreted as follows:
+
+|===
+| `catalog` | The default catalog name.
+| `schemaPattern` | A `%` wild card retrieves data for all schemas of the
specified catalog
+|===
+
+<<<
+[[type-4-driver-conformance-to-sql-data-types]]
+== Type 4 Driver Conformance to SQL Data Types
+
+[[jdbc-data-types]]
+=== JDBC Data Types
+
+The following table shows the JDBC data types that are supported by Type
+4 driver and their corresponding {project-name} SQL data types:
+
+[cols="30%,40%,30%", options="header"]
+|===
+| JDBC Data Type | Support by JDBC Driver for {project-name} SQL
| {project-name} SQL Data Type
+| `Types.Array` | No
| Not applicable.
+| `Types.BIGINT` | Yes
| `LARGEINT`
+| `Types.BINARY` | Data type is mapped by {project-name} SQL. Data
type varies from that used for table creation. | `CHAR(n)`^1^
+| `Types.BIT` | Data type is mapped by {project-name} SQL. Data
type varies from that used for table creation. | `CHAR(1)`
+| `Types.BLOB` | Yes
| `LARGEINT`
+| `Types.CHAR` | Yes
| `CHAR(n)`
+| `Types.CLOB` | Yes
| `LARGEINT`
+| `Types.DATE` | Yes
| `DATE`
+| `Types.DECIMAL` | Yes
| `DECIMAL(p,s)`
+| `Types.DISTINCT` | No
| Not applicable.
+| `Types.DOUBLE` | Yes
| `DOUBLE PRECISION`
+| `Types.FLOAT` | Yes
| `FLOAT(p)`
+| `Types.INTEGER` | Yes
| `INTEGER`
+| `Types.JAVA_OBJECT` | No
| Not applicable.
+| `Types.LONGVARBINARY` | Data type is mapped by {project-name} SQL. Data
type varies from that used for table creation. | `VARCHAR(n)`^1^
+| `Types.LONGVARCHAR` | Yes. Maximum length is 4018.
| `VARCHAR[(n)]`
+| `Types.NULL` | No
| Not applicable.
+| `Types.NUMERIC` | Yes
| `NUMERIC(p,s)`
+| `Types.REAL` | Yes
| `FLOAT(p)`
+| `Types.REF` | No
| Not applicable.
+| `Types.SMALLINT` | Yes
| `SMALLINT`
+| `Types.STRUCT` | No
| Not applicable.
+| `Types.TIME` | Yes
| `TIME`
+| `Types.TIMESTAMP` | Yes
| `TIMESTAMP`
+| `Types.TINYINT` | Data type is mapped by {project-name} SQL. Data
type varies from that used for table creation. | `SMALLINT`
+| `Types.VARBINARY` | Data type is mapped by {project-name} SQL. Data
type varies from that used for table creation. | `VARCHAR(n)`^1^
+| `Types.VARCHAR` | Yes
| `VARCHAR(n)`
+| `Types.BOOLEAN` | Data type is mapped by {project-name} SQL. Data
type varies from that used for table creation. | `CHAR(1)`
+| `Types.DATALINK` | No
| Not applicable.
+|===
+
+^1^ Because of mapping provided by {project-name}, a
`ResultSet.getObject()` method returns a string object instead of an array of
bytes.
+
+The Type 4 driver maps the following data types to the JDBC data type
`Types.OTHER`:
+
+```
+INTERVAL YEAR(p)
+INTERVAL YEAR(p) TO MONTH
+INTERVAL MONTH(p)
+INTERVAL DAY(p)
+INTERVAL DAY(p) TO HOUR
+INTERVAL DAY(p) TO MINUTE
+INTERVAL DAY(p) TO SECOND
+INTERVAL HOUR(p)
+INTERVAL HOUR(p) TO MINUTE
+INTERVAL HOUR(p) TO SECOND
+INTERVAL MINUTE(p)
+INTERVAL MINUTE(p) TO SECOND
+INTERVAL SECOND(p)
+```
+
+[[floating-point-support]]
+== Floating-Point Support
+
+The Type 4 driver supports only IEEE floating-point data to be passed
between the application client and the Type 4 driver.
+
+[[sqlj-support]]
+== SQLJ Support
+
+The Type 4 driver supports non-customized SQLJ applications, but does not
support customized SQLJ applications.
+
+<<<
+[[jdbc-3-0-features-not-supported-by-the-type-4-driver]]
+== JDBC 3.0 Features Not Supported by the Type 4 Driver
+
+These features are not required for JDBC 3.0 compliance, and they are not
supported by the {project-name} JDBC Type 4 driver.
+
+* Multiple result sets returned by batch statements.
+* Database savepoint support. (Not provided in {project-name} SQL )
+* Retrieval of auto generated keys.
+* Transform group and type mapping.
+* Relationship between connector architecture and JDBC 3.0 SPI.
+* Secured socket communication or encryption for the interaction between
the Type 4 driver and DCS.
+* Security context (user name and password) implicit propagation from
AppServer to the Type 4 driver.
+* IPV6 protocol stack. (IPV6 addressing is emulated over IPV4 on the
{project-name} platform - server side)
+* Distributed transactions.
+
+[[restrictions]]
+== Restrictions
+
+* The Type 4 driver supports only database features that are supported by
{project-name} SQL and SPJ.
+Therefore, the Type 4 driver is not fully compliant with JDBC 3.0
specifications.
+
+* The Type 4 driver depends on the HP connectivity service for all server
side manageability related features.
--- End diff --
Changed.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---
