docs: move docs from www/documentation/head (#744)

* docs: move docs from www/documentation/head Move documentation from www/documentation/head/ to pgjdbc/docs/ This makes easy to update the documentation when a change is made to the driver. [skip ci] * update intro
pgjdbc · Feb 7, 2017 · 70e23c45c904ebded42ab1b5efc10d66f34ab68c · 70e23c4
1 parent 8437f6c
commit 70e23c45c904ebded42ab1b5efc10d66f34ab68c
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1 @@
+_site
diff --git a/docs/8-date-time.md b/docs/8-date-time.md
@@ -0,0 +1,77 @@
+---
+layout: default_docs
+title: Using Java 8 Date and Time classes
+header: Chapter 5. Using Java 8 Date and Time classes
+resource: media
+previoustitle: Creating and Modifying Database Objects
+previous: ddl.html
+nexttitle: Chapter 6. Calling Stored Functions
+next: callproc.html
+---
+
+The PostgreSQL™ JDBC driver implements native support for the
+[Java 8 Date and Time API](http://www.oracle.com/technetwork/articles/java/jf14-date-time-2125367.html)
+(JSR-310) using JDBC 4.2.
+
+<a name="8-date-time-supported-data-types"></a>
+**Table 5.1. Supported escaped numeric functions**
+
+<table summary="Supported data type" border="1">
+  <tr>
+    <th>PostgreSQL™</th>
+    <th>Java SE 8</th>
+  </tr>
+  <tbody>
+    <tr>
+      <td>DATE</td>
+      <td>LocalDate</td>
+    </tr>
+    <tr>
+      <td>TIME [ WITHOUT TIMEZONE ]</td>
+      <td>LocalTime</td>
+    </tr>
+    <tr>
+      <td>TIMESTAMP [ WITHOUT TIMEZONE ]</td>
+      <td>LocalDateTime</td>
+    </tr>
+    <tr>
+      <td>TIMESTAMP WITH TIMEZONE</td>
+      <td>OffsetDateTime</td>
+    </tr>
+  </tbody>
+</table>
+
+This is closely aligned with tables B-4 and B-5 of the JDBC 4.2 specification.
+Note that `ZonedDateTime`, `Instant` and
+`OffsetTime / TIME [ WITHOUT TIMEZONE ]` are not supported. Also note
+that all `OffsetDateTime` will instances will have be in UTC (have offset 0).
+This is because the backend stores them as UTC.
+
+<a name="reading-example"></a>
+**Example 5.5. Reading Java 8 Date and Time values using JDBC**
+
+`Statement st = conn.createStatement();`  
+`ResultSet rs = st.executeQuery("SELECT * FROM mytable WHERE columnfoo = 500");`  
+`while (rs.next())`  
+`{`  
+&nbsp;&nbsp;&nbsp;`System.out.print("Column 1 returned ");`  
+&nbsp;&nbsp;&nbsp;`LocalDate localDate = rs.getObject(1, LocalDate.class));`  
+&nbsp;&nbsp;&nbsp;`System.out.println(localDate);`  
+`}`
+`rs.close();`  
+`st.close();` 
+
+For other data types simply pass other classes to `#getObject`.
+Note that the Java data types needs to match the SQL data types in table 7.1.
+
+
+<a name="writing-example"></a>
+**Example 5.5. Writing Java 8 Date and Time values using JDBC**
+
+`LocalDate localDate = LocalDate.now();`  
+`PreparedStatement st = conn.prepareStatement("INSERT INTO mytable (columnfoo) VALUES (?)");`  
+`st.setObject(1, localDate);`  
+`st.executeUpdate();`
+`st.close();`
+
+
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -0,0 +1,3 @@
+name: PostgreSQL JDBC Driver HEAD documentation
+markdown: kramdown
+highlighter: rouge
diff --git a/docs/_layouts/default_docs.html b/docs/_layouts/default_docs.html
@@ -0,0 +1,90 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en" dir="ltr">
+<head>
+	<title>{{ page.title }}</title>
+	<meta http-equiv="Content-Type" content="text/xhtml; charset=utf-8" />
+	<meta name="description" content="The official site for the PostgreSQL JDBC Driver" />
+	<meta name="copyright" content="The PostgreSQL Global Development Group" />
+
+	<style type="text/css" media="screen" title="Normal Text">@import url("{{ page.resource }}/css/docs.css");</style>
+
+	<link rel="shortcut icon" href="media/favicon.ico" />
+</head>
+
+<body>
+	<div id="docHeader">
+		<div id="docHeaderLogo">
+			<a href="http://www.postgresql.org/" title="PostgreSQL"><img src="media/img/layout/hdr_left3a.png" alt="PostgreSQL" height="80" width="390" /></a>
+		</div>
+	</div>
+
+	<div id="docContainerWrap">
+		<div id="docContainer">
+			<div id="docContent">
+
+				<div class="NAVHEADER">
+					<table summary="Header navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
+						<tbody>
+						<tr>
+							<th colspan="3" valign="bottom" align="center">
+								<h2 class="TITLE">{{ page.header }}</h2>
+							</th>
+						</tr>
+						<tr>
+							<td valign="top" width="20%" align="left">
+								<a title="{{ page.previoustitle }}" href="{{ page.previous }}" accesskey="P">Prev</a>
+							</td>
+							<td valign="bottom" width="60%" align="center">&nbsp;</td>
+							<td valign="top" width="20%" align="right">
+								<a title="{{ page.nexttitle }}" href="{{ page.next }}" accesskey="N">Next</a>
+							</td>
+    						</tr>
+  					</tbody>
+					</table>
+					<hr class="c1" width="100%" />
+				</div> <!-- NAVHEADER -->
+
+				<div class="CHAPTER">
+  					<h1>{{ page.title }}</h1>
+					
+					{{ content }}
+				</div>
+
+				<div class="NAVFOOTER">
+					<hr class="c1" width="100%" />
+					<table summary="Footer navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
+					<tbody>
+						<tr>
+							<td valign="top" width="33%" align="left">
+								<a href="{{ page.previous }}" accesskey="P">Prev</a>
+							</td>
+							<td valign="top" width="34%" align="center">
+								<a href="index.html" accesskey="H">Home</a>
+							</td>
+							<td valign="top" width="33%" align="right">
+								<a href="{{ page.next }}" accesskey="N">Next</a>
+							</td>
+    						</tr>
+						<tr>
+							<td valign="top" width="33%" align="left">{{ page.previoustitle }}</td>
+							<td valign="top" width="34%" align="center">&nbsp;</td>
+							<td valign="top" width="33%" align="right">{{ page.nexttitle }}</td>
+						</tr>
+					</tbody>
+					</table>
+				</div> <!-- NAVFOOTER -->
+
+
+			</div> <!-- docContent -->
+			
+			<div id="docComments"></div>
+
+			<div id="docFooter">
+				<a class="navFooter" href="http://www.postgresql.org/about/privacypolicy">Privacy Policy</a> |
+				<a class="navFooter" href="http://www.postgresql.org/about/">About PostgreSQL</a><br/>
+				Copyright &copy; 1996-{{ site.time | date: "%Y" }} The PostgreSQL Global Development Group
+			</div> <!-- pgFooter -->
+		</div> <!-- docContainer -->
+	</div> <!-- docContainer -->
+</body>
+</html>
diff --git a/docs/binary-data.md b/docs/binary-data.md
@@ -0,0 +1,179 @@
+---
+layout: default_docs
+title: Chapter 7. Storing Binary Data
+header: Chapter 7. Storing Binary Data
+resource: media
+previoustitle: Chapter 6. Calling Stored Functions
+previous: callproc.html
+nexttitle: Chapter 8. JDBC escapes
+next: escapes.html
+---
+
+PostgreSQL™ provides two distinct ways to store binary data.  Binary data can be
+stored in a table using the data type BYTEA or by using the Large Object feature
+which stores the binary data in a separate table in a special format and refers
+to that table by storing a value of type OID in your table.
+
+In order to determine which method is appropriate you need to understand the
+limitations of each method. The BYTEA data type is not well suited for storing
+very large amounts of binary data. While a column of type BYTEA can hold up to
+1 GB of binary data, it would require a huge amount of memory to process such a
+large value. The Large Object method for storing binary data is better suited to
+storing very large values, but it has its own limitations.  Specifically deleting
+a row that contains a Large Object reference does not delete the Large Object.
+Deleting the Large Object is a separate operation that needs to be performed.
+Large Objects also have some security issues since anyone connected to the
+database can view and/or modify any Large Object, even if they don't have 
+permissions to view/update the row containing the Large Object reference.
+
+Version 7.2 was the first release of the JDBC driver that supports the BYTEA
+data type. The introduction of this functionality in 7.2 has introduced a change
+in behavior as compared to previous releases. Since 7.2, the methods `getBytes()`,
+`setBytes()`, `getBinaryStream()`, and `setBinaryStream()` operate on the BYTEA
+data type. In 7.1 and earlier, these methods operated on the OID data type
+associated with Large Objects. It is possible to revert the driver back to the
+old 7.1 behavior by setting the property `compatible` on the `Connection` object
+to the value `7.1`. More details on connection properties are available in the
+section called [“Connection Parameters”](connect.html#connection-parameters).
+
+To use the BYTEA data type you should simply use the `getBytes()`, `setBytes()`,
+`getBinaryStream()`, or `setBinaryStream()` methods.
+
+To use the Large Object functionality you can use either the `LargeObject` class
+provided by the PostgreSQL™ JDBC driver, or by using the `getBLOB()` and `setBLOB()`
+methods.
+ 
+### Important
+
+> You must access Large Objects within an SQL transaction block.  You can start a
+transaction block by calling `setAutoCommit(false)`.
+
+[Example 7.1, “Processing Binary Data in JDBC”](binary-data.html#binary-data-example)
+contains some examples on how to process binary data using the PostgreSQL™ JDBC
+driver.
+
+<a name="binary-data-example"></a>
+***Example 7.1. Processing Binary Data in JDBC***
+
+For example, suppose you have a table containing the file names of images and you
+also want to store the image in a BYTEA column:
+
+`CREATE TABLE images (imgname text, img bytea);`
+
+To insert an image, you would use:
+
+`File file = new File("myimage.gif");`  
+`FileInputStream fis = new FileInputStream(file);`  
+`PreparedStatement ps = conn.prepareStatement("INSERT INTO images VALUES (?, ?)");`  
+`ps.setString(1, file.getName());`  
+`ps.setBinaryStream(2, fis, (int)file.length());`  
+`ps.executeUpdate();`  
+`ps.close();`  
+`fis.close();`
+
+Here, `setBinaryStream()` transfers a set number of bytes from a stream into the
+column of type BYTEA. This also could have been done using the `setBytes()` method
+if the contents of the image was already in a `byte[]`. 
+
+### Note
+
+> The length parameter to `setBinaryStream` must be correct. There is no way to
+indicate that the stream is of unknown length. If you are in this situation, you
+must read the stream yourself into temporary storage and determine the length.
+Now with the correct length you may send the data from temporary storage on to
+the driver.
+
+Retrieving an image is even easier. (We use `PreparedStatement` here, but the
+`Statement` class can equally be used.)
+
+`PreparedStatement ps = conn.prepareStatement("SELECT img FROM images WHERE imgname = ?");`  
+`ps.setString(1, "myimage.gif");`  
+`ResultSet rs = ps.executeQuery();`  
+`while (rs.next())`  
+`{`  
+&nbsp;&nbsp;&nbsp;`byte[] imgBytes = rs.getBytes(1);`  
+&nbsp;&nbsp;&nbsp;`// use the data in some way here`  
+`}`  
+`rs.close();`  
+`ps.close();`
+
+Here the binary data was retrieved as an `byte[]`.  You could have used a
+`InputStream` object instead.
+
+Alternatively you could be storing a very large file and want to use the
+`LargeObject` API to store the file:
+
+`CREATE TABLE imageslo (imgname text, imgoid oid);`
+
+To insert an image, you would use:
+
+
+`// All LargeObject API calls must be within a transaction block`  
+`conn.setAutoCommit(false);``<br />
+
+`// Get the Large Object Manager to perform operations with`  
+`LargeObjectManager lobj = conn.unwrap(org.postgresql.PGConnection.class).getLargeObjectAPI();`<br />
+
+`// Create a new large object`  
+`long oid = lobj.createLO(LargeObjectManager.READ | LargeObjectManager.WRITE);`<br />
+
+`// Open the large object for writing`  
+`LargeObject obj = lobj.open(oid, LargeObjectManager.WRITE);`<br />
+
+`// Now open the file`  
+`File file = new File("myimage.gif");`  
+`FileInputStream fis = new FileInputStream(file);`<br />
+
+`// Copy the data from the file to the large object`  
+`byte buf[] = new byte[2048];`  
+`int s, tl = 0;`  
+`while ((s = fis.read(buf, 0, 2048)) > 0)`
+`{`  
+&nbsp;&nbsp;&nbsp;`obj.write(buf, 0, s);`  
+&nbsp;&nbsp;&nbsp;`tl += s;`  
+`}`<br />
+
+`// Close the large object`  
+`obj.close();`<br />
+
+`// Now insert the row into imageslo`  
+`PreparedStatement ps = conn.prepareStatement("INSERT INTO imageslo VALUES (?, ?)");`  
+`ps.setString(1, file.getName());`  
+`ps.setLong(2, oid);`  
+`ps.executeUpdate();`  
+`ps.close();`  
+`fis.close();`<br />
+
+`// Finally, commit the transaction.`  
+`conn.commit();`  
+
+Retrieving the image from the Large Object:
+
+`// All LargeObject API calls must be within a transaction block`  
+`conn.setAutoCommit(false);`<br />
+
+`// Get the Large Object Manager to perform operations with`  
+`LargeObjectManager lobj = conn.unwrap(org.postgresql.PGConnection.class).getLargeObjectAPI();`<br />
+
+`PreparedStatement ps = conn.prepareStatement("SELECT imgoid FROM imageslo WHERE imgname = ?");`  
+`ps.setString(1, "myimage.gif");`  
+`ResultSet rs = ps.executeQuery();`  
+`while (rs.next())`  
+`{`  
+&nbsp;&nbsp;&nbsp;`// Open the large object for reading`  
+&nbsp;&nbsp;&nbsp;`long oid = rs.getLong(1);`  
+&nbsp;&nbsp;&nbsp;`LargeObject obj = lobj.open(oid, LargeObjectManager.READ);`<br />
+
+&nbsp;&nbsp;&nbsp;`// Read the data`  
+&nbsp;&nbsp;&nbsp;`byte buf[] = new byte[obj.size()];`  
+&nbsp;&nbsp;&nbsp;`obj.read(buf, 0, obj.size());`  
+&nbsp;&nbsp;&nbsp;`// Do something with the data read here`<br />
+
+&nbsp;&nbsp;&nbsp;`// Close the object`  
+&nbsp;&nbsp;&nbsp;`obj.close();`  
+`}`  
+`rs.close();`  
+`ps.close();`<br />
+
+`// Finally, commit the transaction.`  
+`conn.commit();`