Docs: Adding try-with-resources to examples and demo. related #938

README.adoc

@@ -62,12 +62,15 @@ id = 2
     {
       public static void main(String[] args)
       {
-        Connection connection = null;
+        // NOTE: Connection and Statement are AutoClosable.
+        //       Don't forget to close them both in order to avoid leaks.
         try
-        {
+        (
           // create a database connection
-          connection = DriverManager.getConnection("jdbc:sqlite:sample.db");
+          Connection connection = DriverManager.getConnection("jdbc:sqlite:sample.db");
           Statement statement = connection.createStatement();
+        )
+        {
           statement.setQueryTimeout(30);  // set timeout to 30 sec.
 
           statement.executeUpdate("drop table if exists person");
@@ -86,20 +89,7 @@ id = 2
         {
           // if the error message is "out of memory",
           // it probably means no database file is found
-          System.err.println(e.getMessage());
-        }
-        finally
-        {
-          try
-          {
-            if(connection != null)
-              connection.close();
-          }
-          catch(SQLException e)
-          {
-            // connection close failed.
-            System.err.println(e.getMessage());
-          }
+          e.printStackTrace(System.err);
         }
       }
     }

USAGE.md

@@ -3,48 +3,54 @@
 Here is an example to establishing a connection to a database file `C:\work\mydatabase.db` (in Windows)
 
 ```java
-Connection connection = DriverManager.getConnection("jdbc:sqlite:C:/work/mydatabase.db");
+try (Connection connection = DriverManager.getConnection("jdbc:sqlite:C:/work/mydatabase.db")) { /*...*/ }
 ```
 
 Opening a UNIX (Linux, maxOS, etc.) file `/home/leo/work/mydatabase.db`
 ```java
-Connection connection = DriverManager.getConnection("jdbc:sqlite:/home/leo/work/mydatabase.db");
+try (Connection connection = DriverManager.getConnection("jdbc:sqlite:/home/leo/work/mydatabase.db")) { /*...*/ }
 ```
 
 ## How to Use Memory Databases
 SQLite supports on-memory database management, which does not create any database files. To use a memory database in your Java code, get the database connection as follows:
 
 ```java
-Connection connection = DriverManager.getConnection("jdbc:sqlite::memory:");
+try (Connection connection = DriverManager.getConnection("jdbc:sqlite::memory:")) { /*...*/ }
 ```
 
 And also, you can create memory database as follows:
 ```java
-Connection connection = DriverManager.getConnection("jdbc:sqlite:");
+try (Connection connection = DriverManager.getConnection("jdbc:sqlite:")) { /*...*/ }
 ```
 
 ## How to use Online Backup and Restore Feature
 Take a backup of the whole database to `backup.db` file:
 
 ```java
-// Create a memory database
-Connection conn = DriverManager.getConnection("jdbc:sqlite:");
-Statement stmt = conn.createStatement();
-// Do some updates
-stmt.executeUpdate("create table sample(id, name)");
-stmt.executeUpdate("insert into sample values(1, \"leo\")");
-stmt.executeUpdate("insert into sample values(2, \"yui\")");
-// Dump the database contents to a file
-stmt.executeUpdate("backup to backup.db");
+try (
+    // Create a memory database
+    Connection conn = DriverManager.getConnection("jdbc:sqlite:");
+    Statement stmt = conn.createStatement();
+) {
+    // Do some updates
+    stmt.executeUpdate("create table sample(id, name)");
+    stmt.executeUpdate("insert into sample values(1, \"leo\")");
+    stmt.executeUpdate("insert into sample values(2, \"yui\")");
+    // Dump the database contents to a file
+    stmt.executeUpdate("backup to backup.db");
+}
 ```
 
 Restore the database from a backup file:
 ```java
-// Create a memory database
-Connection conn = DriverManager.getConnection("jdbc:sqlite:");
-// Restore the database from a backup file
-Statement stat = conn.createStatement();
-stat.executeUpdate("restore from backup.db");
+try (
+    // Create a memory database
+    Connection conn = DriverManager.getConnection("jdbc:sqlite:");
+    // Restore the database from a backup file
+    Statement stat = conn.createStatement();
+) {
+    stat.executeUpdate("restore from backup.db");
+}
 ```
 
 ## Creating BLOB data
@@ -62,18 +68,18 @@ use `jdbc:sqlite::resource:` prefix.
 For example, here is an example to access an SQLite DB file, `sample.db` 
 in a Java package `org.yourdomain`:
 ```java
-Connection conn = DriverManager.getConnection("jdbc:sqlite::resource:org/yourdomain/sample.db");
+try (Connection conn = DriverManager.getConnection("jdbc:sqlite::resource:org/yourdomain/sample.db")) { /*...*/ }
 ```
 
 In addition, external DB resources can be used as follows:
 ```java
-Connection conn = DriverManager.getConnection("jdbc:sqlite::resource:http://www.xerial.org/svn/project/XerialJ/trunk/sqlite-jdbc/src/test/java/org/sqlite/sample.db");
+try (Connection conn = DriverManager.getConnection("jdbc:sqlite::resource:http://www.xerial.org/svn/project/XerialJ/trunk/sqlite-jdbc/src/test/java/org/sqlite/sample.db")) { /*...*/ }
 ```
 
 To access db files inside some specific jar file (in local or remote), 
 use the [JAR URL](http://java.sun.com/j2se/1.5.0/docs/api/java/net/JarURLConnection.html):
 ```java
-Connection conn = DriverManager.getConnection("jdbc:sqlite::resource:jar:http://www.xerial.org/svn/project/XerialJ/trunk/sqlite-jdbc/src/test/resources/testdb.jar!/sample.db");
+try (Connection conn = DriverManager.getConnection("jdbc:sqlite::resource:jar:http://www.xerial.org/svn/project/XerialJ/trunk/sqlite-jdbc/src/test/resources/testdb.jar!/sample.db")) { /*...*/ }
 ```
 
 DB files will be extracted to a temporary folder specified in `System.getProperty("java.io.tmpdir")`.
@@ -102,7 +108,7 @@ SQLiteConfig config = new SQLiteConfig();
 config.setSharedCache(true);
 config.recursiveTriggers(true);
 // ... other configuration can be set via SQLiteConfig object
-Connection conn = DriverManager.getConnection("jdbc:sqlite:sample.db", config.toProperties());
+try (Connection conn = DriverManager.getConnection("jdbc:sqlite:sample.db", config.toProperties())) { /*...*/ }
 ```
 
 ## How to Use Encrypted Databases
@@ -116,7 +122,7 @@ SQLite support encryption of the database via special drivers and a key. To use
 
 Now the only need to specify the password is via:
 ```java
-Connection connection = DriverManager.getConnection("jdbc:sqlite:db.sqlite", "", "password");
+try (Connection connection = DriverManager.getConnection("jdbc:sqlite:db.sqlite", "", "password")) { /*...*/ }
 ```
 
 ### Binary Passphrase
@@ -130,7 +136,7 @@ The binary password is provided via `pragma key="x'AE...'"`
 
 You set the mode at the connection string level:
 ```java
-Connection connection = DriverManager.getConnection("jdbc:sqlite:db.sqlite?hexkey_mode=sse", "", "AE...");
+try (Connection connection = DriverManager.getConnection("jdbc:sqlite:db.sqlite?hexkey_mode=sse", "", "AE...")) { /*...*/ }
 ```
 
 ## Explicit read only transactions (use with Hibernate)
@@ -160,7 +166,7 @@ config.setExplicitReadOnly(true);
 ```
 - using the pragma `jdbc.explicit_readonly`:
 ```java
-DriverManager.getConnection("jdbc:sqlite::memory:?jdbc.explicit_readonly=true");
+try (Connection connection = DriverManager.getConnection("jdbc:sqlite::memory:?jdbc.explicit_readonly=true")) { /*...*/ }
 ```
 
 ## How to use with Android

demo/Sample.java

@@ -8,12 +8,15 @@ public class Sample
     {
       public static void main(String[] args) 
       {
-        Connection connection = null;
+        // NOTE: Connection and Statement are AutoClosable.
+        //       Don't forget to close them both in order to avoid leaks.
         try
-        {
+        (
           // create a database connection
-          connection = DriverManager.getConnection("jdbc:sqlite:sample.db");
+          Connection connection = DriverManager.getConnection("jdbc:sqlite:sample.db");
           Statement statement = connection.createStatement();
+        )
+        {
           statement.setQueryTimeout(30);  // set timeout to 30 sec.
 
           statement.executeUpdate("drop table if exists person");
@@ -32,20 +35,7 @@ public static void main(String[] args)
         {
           // if the error message is "out of memory", 
           // it probably means no database file is found
-          System.err.println(e.getMessage());
-        }
-        finally
-        {
-          try
-          {
-            if(connection != null)
-              connection.close();
-          }
-          catch(SQLException e)
-          {
-            // connection close failed.
-            System.err.println(e);
-          }
+          e.printStackTrace(System.err);
         }
       }
     }