Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673116
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/accessing.adoc ---
@@ -0,0 +1,910 @@
+////
+/**
+ *@@@ 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 @@@
+ */
+////
+
+[[accessing-project-name-sql-databases]]
+= Accessing {project-name} SQL Databases
+
+[[data-sources]]
+== Data Sources
+
+The term *data source* logically refers to a database or other data
+storage entity. A JDBC (client) data source is physically a Java object
that
+contains properties such as the URL of the physical database, the
+catalog to use when connecting to this database, and the schema to use
+when connecting to this database. The JDBC data source also contains
+methods for obtaining a JDBC connection to the underlying database.
+
+[[jdbc-data-source-client-side]]
+=== JDBC Data Source (client-side)
+
+All JDBC data source classes implement either the `javax.sql.DataSource`
+interface or the `javax.sql.ConnectionPoolDataSource` interface. The Type
+4 driver data source classes are `org.trafodion.t4jdbc.HPT4DataSource` and
+`org.trafodion.t4jdbc.HPT4ConnectionPoolDataSource`. (These classes are
+defined by the JDBC 3.0 specification.)
+
+Typically, a user or system administrator uses a tool to create a data
+source, and then registers the data source by using a JNDI service
+provider. At run time, a user application typically retrieves the data
+source through JNDI, and uses the data source's methods to establish a
+connection to the underlying database.
+
+A DataSource object maps to an instance of a database. In the Type 4
+driver product, the DataSource object acts as an interface between the
+application code and the database and enables connection with an DCS
+data source.
+
+[[security]]
+== Security
+
+Clients connect to the {project-name} platform with a valid user name
+and ID, using standard JDBC 3.0 APIs. An application can make multiple
+connections using different user IDs, and creating different Connection
+objects.
+
+The Type 4 driver provides for user name and password authentication.
+The password is encrypted with a proprietary algorithm provided by DCS.
+
+NOTE: There is no secure wire communication such as SSL provided for the
+communication between Type 4 driver and the {project-name} platform.
+
+<<<
+[[connection-by-using-the-datasource-interface]]
+== Connection by Using the DataSource Interface
+
+The `javax.sql.DataSource` interface is the preferred way to establish a
+connection to the database because this interface enhances the application
+portability. Portability is achieved by allowing the application to use a
+logical name for a data source instead of providing driver-specific
information
+in the application. A logical name is mapped to a `javax.sql.DataSource`
+object through a naming service that uses the Java Naming and Directory
+Interface (JNDI). Using this DataSource method is particularly recommended
+for application servers.
+
+When an application requests a connection by using the `getConnection`
method
+in the `DataSource`, then the method returns a `Connection` object.
+
+A `DataSource` object is a factory for `Connection` objects. An object that
+implements the `DataSource` interface is typically registered with a JNDI
+service provider.
+
+[[overview-of-tasks-to-deploy-datasource-objects]]
+=== Overview of Tasks to Deploy DataSource Objects
+
+Before an application can connect to a `DataSource` object, typically
+the system administrator deploys the `DataSource` object so that
+the application programmers can start using it.
+
+Data source properties are usually set by a system administrator using
+a GUI tool as part of the installation of the data source. Users to
+the data source do not get or set properties. Management tools can get
+at properties by using introspection.
+
+Tasks involved in creating and registering a database object are:
+
+1. Creating an instance of the `DataSource` class.
+2. Setting the properties of the `DataSource` object.
+3. Registering the `DataSource` object with a naming service that uses
+the Java Naming and Directory Interface (JNDI) API.
+
+An instance of the `DataSource` class and the `DataSource` object
+properties are usually set by an application developer or system
+administrator using a GUI tool as part of the installation of the
+data source. If you are using an installed data source, then see
+<<programmatically-creating-an-instance-of-the-datasource-class,
Programmatically Creating an Instance of the DataSource Class>>.
+
+The subsequent topics show an example of performing these tasks
programmatically.
+
+For more information about using data sources, see
https://docs.oracle.com/javase/tutorial/jdbc/basics/sqldatasources.html[Connecting
with DataSource Objects]
+in the https://docs.oracle.com/javase/tutorial/jdbc/TOC.html[JDBC(TM)
Database Access: Table of Contents] documentation
+or other information available in the field.
+
+<<<
+[[datasource-object-properties]]
+=== DataSource Object Properties
+
+A `DataSource` object has properties that identify and describe the actual
+data source that the object represents. These properties include such
+information as the URL (the primary IP address or host name of the
database),
+the database schema and catalog names, the location of the database server,
+the name of the database, and so forth.
+
+For details about Type 4 driver properties that you can use with the
`DataSource` object, see <<type-4-driver-properties,Type 4 Driver Properties>>.
+
+[[programmatically-creating-an-instance-of-the-datasource-class]]
+=== Programmatically Creating an Instance of the DataSource Class
+
+A JDBC application can set `DataSource` properties programmatically and
+register with a DataSource object. To get or set `DataSource` object
properties programmatically, use the
+appropriate getter or setter methods on the `HPT4DataSource` object or
+the `HPT4ConnectionPoolDataSource` object.
+
+*Example*
+
+[source, java]
+----
+HPT4DataSource temp = new HPT4DataSource() ;
+temp.setCatalog( "Seabase" ) ;
+----
+
+In the following example, the code fragment illustrates the methods that a
+`DataSource` object `ds` needs to include if the object supports the
+`serverDataSource` property `ds.setServerDataSource(
"my_server_datasource" )`.
+In this example, the code shows setting properties for the
`HPT4DataSource` object
+to use the Type 4 driver to access a {project-name} database:
+
+[source, java]
+----
+HPT4DataSource ds = new HPT4DataSource() ;
+
+ds.setUrl( "jdbc:hpt4jdbc://<primary IP addr or host name>:18650/" );
+ds.setCatalog( "Seabase" ) ;
+ds.setSchema( "myschema" ) ;
+ds.setUser( "gunnar" ) ;
+ds.setPassword( "my_userpassword" ) ;
+
+// Properties relevant for Type 4 connection pooling.
+// Set ds.setMaxPoolSize(-1) for turning OFF connection pooling
+ds.setMaxPoolSize( "10000" ) ;
+ds.setMinPoolSize( "1000" ) ;
+
+// Properties relevant for Type 4 statement pooling.
+// Set ds.setMaxStatement(0) for turning statement pooling OFF
+// Statement pooling is enabled only when connection pooling is
+// enabled.
+ds.setMaxStatements( "7000" ) ;
+----
+
+This technique essentially builds a properties file. For more information,
+see <<creating-and-using-a-properties-file, Creating and Using a
Properties File>>.
+
+[[programmatically-registering-the-datasource-object]]
+=== Programmatically Registering the DataSource Object
+
+In the following example, the code shows how to register, programmatically,
+the `HPT4DataSource` object `ds` that was created using the preceding code
with JNDI.
+
+[source, java]
+----
+java.util.Hashtable env = new java.util.Hashtable() ;
+env.put( Context.INITIAL_CONTEXT_FACTORY, "Factory class name here" ) ;
+
+javax.naming.Context ctx = new javax.naming.InitialContext( env ) ;
+ctx.rebind( "myDataSource", ds ) ;
+----
+
+[[retrieving-a-datasource-instance-by-using-jndi-and-connecting-to-the-data-source]]
+=== Retrieving a DataSource Instance by Using JNDI and Connecting to the
Data Source
+Typically, the JDBC application looks up the data source JNDI name from a
+context object. Once the application has the `DataSource` object, then the
application
+does a `getConnection()` call on the data source and gets a connection.
+
+The steps that JDBC application does to connect to and use the data source
associated
+with the database are listed below together with the application code to
perform the
+operation.
+
+1. Import the packages.
++
+[source, java]
+----
+import javax.naming.* ;
+import java.sql.* ;
+import javax.sql.DataSource ;
+----
+
+2. Create the initial context.
++
+[source, java]
+----
+Hashtable env = new Hashtable() ;
+env.put( Context.INITIAL_CONTEXT_FACTORY,
"com.sun.jndi.fscontext.RefFSContextFactory" ) ;
+try
+{
+ Context ctx = new InitialContext( env ) ;
+}
+catch( ... )
+{
+...
+}
+----
++
+<<<
+3. Look up the JNDI name associated with the data source `myDataSource`,
where `myDataSource`
+is the logical name that will be associated with the real-world data
source - server.
++
+[source, java]
+----
+DataSource ds = (DataSource)ctx.lookup( "myDataSource" ) ;
+----
+
+4. Create the connection using the data source.
++
+[source, java]
+----
+con = ds.getConnection() ;
+----
+
+5. Do work with the connection. The following statements are just a simple
example.
++
+[source, java]
+----
+stmt = con.createStatement() ;
+try
+{
+ stmt.executeUpdate( "drop table tdata" ) ;
+}
+catch ( SQLException e ) {}
+----
+
+[[specifying-the-properties-file-that-configures-the-data-source]]
+=== Specifying the Properties File that Configures the Data Source
+
+To use the properties file method to configure a `DataSource` object, the
properties
+file must exist on disk and contain the `property_name=property_value`
pairs that
+configure the data source.
+See <<creating-and-using-a-properties-file, Creating and Using a
Properties File>>
+for more information about creating this file.
+
+When the JDBC application makes the connection, then the application should
+pass the properties file as a command-line parameter:
+
+```
+java -Dhpt4jdbc.properties=<path of properties file on disk>
+```
+
+[[connection-by-using-the-drivermanager-class]]
+== Connection by Using the DriverManager Class
+
+The `java.sql.DriverManager` class is widely used to get a connection, but
+is less portable than the `DataSource` class. The `DriverManager` class
+works with the Driver interface to manage the set of drivers loaded.
+When an application issues a request for a connection using the
+`DriverManager.getConnection` method and provides a URL, the
`DriverManager`
+finds a suitable driver that recognizes this URL and obtains a database
+connection using that driver.
+
+`org.trafodion.t4jdbc.HPT4Driver` is the Type 4 driver class that
+implements the `java.sql.Driver` interface.
+
+<<<
+[[loading-and-registering-the-driver]]
+=== Loading and Registering the Driver
+
+Before connecting to the database, the application loads the Driver
+class and registers the Type 4 driver with the DriverManager class in
+one of the following ways:
+
+* Specifies the Type 4 driver class in the `-Djdbc.drivers` option in the
+command line of the Java program:
++
+```
+-Djdbc.drivers=org.trafodion.t4jdbc.HPT4Driver
+```
+
+* Uses the `Class.forName` method programmatically within the application:
++
+[source, java]
+----
+Class.forName("org.trafodion.t4jdbc.HPT4Driver")
+----
+
+* Adds the Type 4 driver class to the `java.lang.System` property
+`jdbc.drivers` property within the application:
++
+```
+jdbc.drivers=org.trafodion.t4jdbc.HPT4Driver
+```
+
+<<<
+[[establishing-the-connection]]
+=== Establishing the Connection
+
+The `DriverManager.getConnection` method accepts a string containing a
+Type 4 driver URL. The JDBC URL for the Type 4 driver is
+
+```
+jdbc:hpt4jdbc://<ip addr or host
name>:3700/[:][property=value[;property2=value2]...]
+```
+
+[cols="40%,60%", options="header"]
+|===
+| Parameter | Usage
+| `<ip addr or host name>` | The primary IP address or host name for the
{project-name} database.
+| `37800` | The port number for the {project-name} SQL
database.
+| `property = value` and `property2=value2` | Specifies a Type 4 driver
property name-property value pair. The pairs must be separated by a
+semicolon (`;`). For example, `T4LogLevel=ALL;T4LogFile=temp1.log`.
+|===
+
+For information about the properties file, see
<<type-4-driver-properties,Type 4 Driver Properties>>.
+
+To establish a connection, the JDBC application can use this code:
+
+[source, java]
+----
+Class.forName( "org.trafodion.t4jdbc.HPT4Driver" ) ; //loads the driver
+
+String url = "jdbc:hpt4jdbc://<database primary IP address>:37800/"
+
+Connection con = DriverManager.getConnection( url, "userID", "Passwd" ) ;
+----
+
+The variable con represents a connection to the data source that can be
+used to create and execute SQL statements.
+
+[[guidelines-for-connections-using-the-driver-manager]]
+=== Guidelines for Connections Using the Driver Manager
+
+* The Type 4 driver defines a set of properties that you can use to
+configure the driver. For detailed information about these properties,
+see <<type-4-driver-properties,Type 4 Driver Properties>>.
+* Java applications can specify the properties in these ways (listed in
+the order of precedence):
++
+1. Using the `java.util.Properties` parameter in the `getConnection`
method of DriverManager class.
+
+2. Using the database URL in the `DriverManager.getconnection` method,
where the URL is:
++
+```
+jdbc:hpt4jdbc://<ip addr or host name>:37800/:property=value
+```
++
+`<ip addr or host name>` is the primary IP address or host name for the
{project-name} database.
++
+<<<
+3. Using a properties file for the JDBC driver. The properties file is
+passed as a command-line parameter. The format to enter the properties
+file in the command line is:
++
+```
+-Dhpt4jdbc.properties=<path of properties file on disk>
+```
++
+For example, `-Dhpt4jdbc.properties=C:\temp\t4props`
++
+For information about the properties file, see
<<creating-and-using-a-properties-file, Creating and Using a Properties File>>.
+4. Using JDBC properties with the `-D` option in the command line. If
+used, this option applies to all JDBC connections using the
+`DriverManager` within the Java application. The format in the command
+line is:
++
+```
+-Dhpt4jdbc.property_name=<property value>
--- 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.
---
