README.md

   1 # SQLiteMap &ndash; a map implementation based on SQLite
   2
   3 ![JDK8](https://img.shields.io/badge/JDK-8%2B-blue) ![SQLite3](https://img.shields.io/badge/SQLite-3.36-blue) ![JUnit5](https://img.shields.io/badge/JUnit-5.8-blue) ![GitHub all releases](https://img.shields.io/github/downloads/lordmulder/sqlitemap/total)
   4
   5 The **`SQLiteMap`** class provides a [`Map`](https://docs.oracle.com/javase/8/docs/api/java/util/Map.html) implementation that is backed by an [*SQLite*](https://www.sqlite.org/) database. It can employ an "in-memory" database as well as a local database file. Compared to Java's standard `HashMap` class, the "in-memory" variant of `SQLiteMap` is better suited for *very large* maps; it has a smaller memory footprint and it does **not** clutter the Java heap space. The file-based variant of `SQLiteMap` provides full persistence.
   6
   7 `SQLiteMap` is compatible with JDK 8 or later. We recommend using OpenJDK builds provided by [Adoptium.net](https://adoptium.net/).
   8
   9
  10 ## Getting started
  11
  12 This example shows how to create and use an "in-memory" **`SQLiteMap`** instance:
  13
  14     import java.util.Map.Entry;
  15     import com.muldersoft.container.sqlite.SQLiteMap;
  16
  17     public class Main {
  18       public static void main(String[] args) throws Exception {
  19         try (final SQLiteMap<String, String> map = SQLiteMap.fromMemory(String.class, String.class)) {
  20           map.put0("Foo", "Lorem ipsum dolor sit amet");
  21           map.put0("Bar", "Consetetur sadipscing elitr");
  22           for (final Entry<String, String> e : map.entrySet()) {
  23             System.out.println('"' + e.getKey() + "\" --> \"" + e.getValue() + '"');
  24           }
  25         }
  26       }
  27     }
  28
  29 &#128073; Please see the included **documentation** (Javadoc) for details!
  30
  31
  32 ## Dependencies
  33
  34 ### *Runtime* dependencies:
  35
  36 `SQLiteMap` requires the [**SQLite JDBC Driver**](https://mvnrepository.com/artifact/org.xerial/sqlite-jdbc), version 3.36 or newer, to be available in the classpath at runtime!
  37
  38 ### *Build* dependencies:
  39
  40 In order to build `SQLiteMap` from the sources, [**JDK 17**](https://adoptium.net/releases.html?variant=openjdk17) and [**Apache Ant**](https://ant.apache.org/), version 1.10.x (or later), are required!
  41
  42 Make sure that the environment variables `JAVA_HOME` and `ANT_HOME` are pointing to the JDK 17 home directory and the Ant home directory, respectively. Also make sure that [**ant**](http://manpages.ubuntu.com/manpages/trusty/man1/ant.1.html) and [**git**](https://git-scm.com/docs/git) can be found in your `PATH`.
  43
  44 The provided *Apache Ant* buildfile (`build.xml`) requires [**Apache Commons BCEL**](https://mvnrepository.com/artifact/org.apache.bcel/bcel) to be available in the Ant's classpath! A simple way to achieve this is copying the required JAR file into your `${ANT_HOME}/lib` directory.
  45
  46 Finally, the environment variable `JDK8_BOOT_PATH` needs to be pointing to the `rt.jar` library from [**JDK 8**](https://adoptium.net/releases.html?variant=openjdk8).
  47
  48
  49 ### *Test* dependencies:
  50
  51 In order to compile the *JUnit* tests, the [**JUnit Jupiter API**](https://mvnrepository.com/artifact/org.junit.jupiter/junit-jupiter-api/), version 5.x, needs to be present in the `lib` directory!
  52
  53
  54 ## Building and Testing
  55
  56 ### Building the library:
  57
  58 In order to build the `SQLiteMap` library, simply run **`ant`** from the project's base directory:
  59
  60     $ cd ~/workspace/sqlitemap
  61     $ ant
  62
  63 The *default* target `all` compiles the source code (except tests), generates the Javadoc and builds the JAR files.
  64
  65 ### Running the JUnit tests:
  66
  67 In order to run the [**JUnit 5**](https://junit.org/junit5/) tests, the test classes need to be *compiled* first:
  68
  69     $ ant clean compile-test
  70
  71 Then the [JUnit Console Launcher](https://mvnrepository.com/artifact/org.junit.platform/junit-platform-console-standalone) may be invoked from the project's base directory, for example:
  72
  73     $ java -jar junit-platform-console-standalone.jar -cp lib/sqlite-jdbc-<version>.jar -cp bin \
  74         --include-classname='(.*)SQLite(.+)Test$' --scan-classpath
  75
  76
  77 ## Source Code
  78
  79 The source code is available from the "official" Git mirrors:
  80
  81 | Mirror     | URL                                                        | Browse                                                        |
  82 | ---------- | ---------------------------------------------------------- | --------------------------------------------------------------|
  83 | GitHub     | `git clone https://github.com/lordmulder/SQLiteMap.git`    | [&#128279; link](https://github.com/lordmulder/SQLiteMap)     |
  84 | Bitbucket  | `git clone https://bitbucket.org/muldersoft/sqlitemap.git` | [&#128279; link](https://bitbucket.org/muldersoft/sqlitemap/) |
  85 | GitLab     | `git clone https://gitlab.com/lord_mulder/sqlitemap.git  ` | [&#128279; link](https://gitlab.com/lord_mulder/sqlitemap)    |
  86 | repo.or.cz | `git clone https://repo.or.cz/sqlitemap.git`               | [&#128279; link](https://repo.or.cz/sqlitemap.git)            |
  87
  88
  89 ## Download
  90
  91 Download the latest *binary* distribution here:
  92 **<https://github.com/lordmulder/SQLiteMap/releases/latest>**
  93
  94
  95 ### Code signature:
  96
  97 The following [**OpenPGP key**](http://muldersoft.com/#signkey) is used to sign all "official" releases binaries:
  98
  99     pub   rsa4096 2015-08-23 [expires: 2025-08-20]
 100           DFAD 4340 D83D 4020 435D 78BB 2B59 1336 5F57 E03F
 101     uid   LoRd_MuldeR (muldersoft.com)
 102
 103 See [*here*](https://www.gnupg.org/gph/en/manual/x135.html) for details on how to verify file signatures using [GnuPG](https://www.gnupg.org/). Windows users should refer to [Gpg4win](https://www.gpg4win.de/).
 104
 105
 106 ## License
 107
 108 `SQLiteMap` was created by LoRd_MuldeR [&lt;mulder2@gmx.de&gt;](mailto:mulder2@gmx.de).
 109
 110 To the extent possible under law, the person who associated **CC0** with `SQLiteMap` has waived all copyright and related or neighboring rights to `SQLiteMap`. You should have received a copy of the **CC0** legalcode along with this work.
 111
 112 If not, please refer to:
 113 <http://creativecommons.org/publicdomain/zero/1.0/>
 114
 115
 116 &nbsp;
 117
 118 [&#128020;](https://www.youtube.com/watch?v=VF9UMona74w)