Skip to content

Commit

Permalink
add syntax highlight to documentation
Browse files Browse the repository at this point in the history 
[skip ci]
  • Loading branch information
@jorsol @vlsi
jorsol authored and vlsi committed Feb 18, 2017
1 parent cafe58a commit 78360e6
Show file tree
Hide file tree
Showing 21 changed files with 457 additions and 341 deletions.
15 changes: 8 additions & 7 deletions docs/_layouts/default_docs.html
View file
Original file line number Diff line number Diff line change
@@ -1,20 +1,21 @@
<!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">
<!DOCTYPE html>
<html>
<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 http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="description" content="The official documentation 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>
<style type="text/css" media="screen" title="Normal Text">@import url("media/css/docs.css");</style>
<link rel="stylesheet" type="text/css" href="{{ page.resource }}/css/syntax.css">

<link rel="shortcut icon" href="media/favicon.ico" />
<link rel="shortcut icon" href="{{ page.resource }}/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>
<a href="https://www.postgresql.org/" title="PostgreSQL"><img src="media/img/layout/hdr_left3a.png" alt="PostgreSQL" height="80" width="390" /></a>
</div>
</div>

Expand Down
169 changes: 90 additions & 79 deletions docs/documentation/head/binary-data.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,18 +58,22 @@ driver.
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);`
```sql
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();`
```java
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
Expand All @@ -86,94 +90,101 @@ 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();`
```java
PreparedStatement ps = conn.prepareStatement("SELECT img FROM images WHERE imgname = ?");
ps.setString(1, "myimage.gif");
ResultSet rs = ps.executeQuery();
while (rs.next())
{
byte[] imgBytes = rs.getBytes(1);
// 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);`
```sql
CREATE TABLE imageslo (imgname text, imgoid oid);
```

To insert an image, you would use:

```java
// All LargeObject API calls must be within a transaction block
conn.setAutoCommit(false);

`// 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();

`// 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);

`// 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);

`// 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);

`// 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)
{
obj.write(buf, 0, s);
tl += s;
}

`// 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();

`// 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();

`// 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();`
// 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();`
```java
// All LargeObject API calls must be within a transaction block
conn.setAutoCommit(false);

// Get the Large Object Manager to perform operations with
LargeObjectManager lobj = conn.unwrap(org.postgresql.PGConnection.class).getLargeObjectAPI();

PreparedStatement ps = conn.prepareStatement("SELECT imgoid FROM imageslo WHERE imgname = ?");
ps.setString(1, "myimage.gif");
ResultSet rs = ps.executeQuery();
while (rs.next())
{
// Open the large object for reading
long oid = rs.getLong(1);
LargeObject obj = lobj.open(oid, LargeObjectManager.READ);

// Read the data
byte buf[] = new byte[obj.size()];
obj.read(buf, 0, obj.size());
// Do something with the data read here

// Close the object
obj.close();
}
rs.close();
ps.close();

// Finally, commit the transaction.
conn.commit();
```
102 changes: 55 additions & 47 deletions docs/documentation/head/callproc.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,12 +21,14 @@ next: binary-data.html
This example shows how to call a PostgreSQL™ built in function, `upper`, which
simply converts the supplied string argument to uppercase.

`CallableStatement upperProc = conn.prepareCall("{ ? = call upper( ? ) }");`
`upperProc.registerOutParameter(1, Types.VARCHAR);`
`upperProc.setString(2, "lowercase to uppercase");`
`upperProc.execute();`
`String upperCased = upperProc.getString(1);`
`upperProc.close();`
```java
CallableStatement upperProc = conn.prepareCall("{ ? = call upper( ? ) }");
upperProc.registerOutParameter(1, Types.VARCHAR);
upperProc.setString(2, "lowercase to uppercase");
upperProc.execute();
String upperCased = upperProc.getString(1);
upperProc.close();
```

<a name="callproc-resultset"></a>
# Obtaining a `ResultSet` from a stored function
Expand All @@ -46,16 +48,18 @@ interfaces.
<a name="setof-resultset"></a>
**Example 6.2. Getting `SETOF` type values from a function**

`Statement stmt = conn.createStatement();`
`stmt.execute("CREATE OR REPLACE FUNCTION setoffunc() RETURNS SETOF int AS "`
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`+ "' SELECT 1 UNION SELECT 2;' LANGUAGE sql");`
`ResultSet rs = stmt.executeQuery("SELECT * FROM setoffunc()");`
`while (rs.next())`
`{`
&nbsp;&nbsp;&nbsp;`// do something`
`}`
`rs.close();`
`stmt.close();`
```java
Statement stmt = conn.createStatement();
stmt.execute("CREATE OR REPLACE FUNCTION setoffunc() RETURNS SETOF int AS "
+ "' SELECT 1 UNION SELECT 2;' LANGUAGE sql");
ResultSet rs = stmt.executeQuery("SELECT * FROM setoffunc()");
while (rs.next())
{
// do something
}
rs.close();
stmt.close();
```

<a name="callproc-resultset-refcursor"></a>
## From a Function Returning a refcursor
Expand All @@ -75,31 +79,33 @@ and it is technically possible to remove it, we just haven't found the time.
<a name="get-refcursor-from-function-call"></a>
**Example 6.3. Getting refcursor Value From a Function**

`// Setup function to call.`
`Statement stmt = conn.createStatement();`
`stmt.execute("CREATE OR REPLACE FUNCTION refcursorfunc() RETURNS refcursor AS '"`
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`+ " DECLARE "`
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`+ " mycurs refcursor; "`
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`+ " BEGIN "`
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`+ " OPEN mycurs FOR SELECT 1 UNION SELECT 2; "`
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`+ " RETURN mycurs; "`
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`+ " END;' language plpgsql");`
`stmt.close();`<br />

`// We must be inside a transaction for cursors to work.`
`conn.setAutoCommit(false);`<br />

`// Procedure call.`
`CallableStatement proc = conn.prepareCall("{ ? = call refcursorfunc() }");`
`proc.registerOutParameter(1, Types.OTHER);`
`proc.execute();`
`ResultSet results = (ResultSet) proc.getObject(1);`
`while (results.next())`
`{`
&nbsp;&nbsp;&nbsp;`// do something with the results.`
`}`
`results.close();`
`proc.close();`
```java
// Setup function to call.
Statement stmt = conn.createStatement();
stmt.execute("CREATE OR REPLACE FUNCTION refcursorfunc() RETURNS refcursor AS '"
+ " DECLARE "
+ " mycurs refcursor; "
+ " BEGIN "
+ " OPEN mycurs FOR SELECT 1 UNION SELECT 2; "
+ " RETURN mycurs; "
+ " END;' language plpgsql");
stmt.close();

// We must be inside a transaction for cursors to work.
conn.setAutoCommit(false);

// Procedure call.
CallableStatement proc = conn.prepareCall("{ ? = call refcursorfunc() }");
proc.registerOutParameter(1, Types.OTHER);
proc.execute();
ResultSet results = (ResultSet) proc.getObject(1);
while (results.next())
{
// do something with the results.
}
results.close();
proc.close();
```

It is also possible to treat the refcursor return value as a cursor name directly.
To do this, use the `getString` of `ResultSet`. With the underlying cursor name,
Expand All @@ -108,9 +114,11 @@ you are free to directly use cursor commands on it, such as `FETCH` and `MOVE`.
<a name="refcursor-string-example"></a>
**Example 6.4. Treating refcursor as a cursor name**

`conn.setAutoCommit(false);`
`CallableStatement proc = conn.prepareCall("{ ? = call refcursorfunc() }");`
`proc.registerOutParameter(1, Types.OTHER);`
`proc.execute();`
`String cursorName = proc.getString(1);`
`proc.close();`
```java
conn.setAutoCommit(false);
CallableStatement proc = conn.prepareCall("{ ? = call refcursorfunc() }");
proc.registerOutParameter(1, Types.OTHER);
proc.execute();
String cursorName = proc.getString(1);
proc.close();
```
Loading

0 comments on commit 78360e6

Please sign in to comment.