Getting Started (Deprecated)

1. To play with Jinq, you must first download version 0.8 of the Jinq source code and unpack it somewhere.
2. Jinq requires Java 8. Be sure you have the latest Java 8 JDK from Oracle installed.
3. Jinq also uses requires the use of ASM for its bytecode analysis. You need to download the asm-5.0.1-bin.zip release, and copy the asm-5.0.1/lib/all/asm-all-5.0.1.jar file from the .zip archive to the lib directory of Jinq.
4. You can now go into the Jinq directory and run ant to build and run Jinq and its sample project.

Understanding the Sample Project

• Running ant to build Jinq does four things:
1. It compiles and builds Jinq
2. It uses a mini-ORM (object relational mapper) to create entity classes that can be used to represent objects stored in the tables of a SQL database
3. It compiles a small demo that executes some simple Jinq queries using these entity classes
4. It runs this small demo
• More information about each of these steps is given below.

Compiling Jinq

• Jinq does not require any special compilers or debuggers. You just need to include the Jinq libraries in with your code, and you can start using Jinq.
• Jinq is able to do this by using advanced bytecode analysis algorithms to analyze your compiled Java code and translate it into SQL database queries

Jinq Mini-ORM

• In order to work with database data in Java, you need an object-oriented representation of the data. Jinq uses a simple mini-ORM for this purpose.
• A description of the various entities of the database, of the relationship between those entities, and how these entities should be mapped to SQL tables is given to the mini-ORM as input.
• The description of the database data for the sample program is defined in demosrc/entities.xml
• The mini-ORM takes this description and generates some classes to represent different entities of the database
• For the sample program, the generated classes are outputted to the demogen/ directory
• In addition to the classes used to represent database entities, Jinq also creates two special classes DBManager and EntityManager.
• The DBManager is used to open a connection to a database and to start and close transactions on that database
• The EntityManager is used manage the objects during a transaction. In Jinq, programmers write database queries by getting a Set of "all the data in a database" and then filtering that set to get the data you want. The EntityManager is where the programmer goes to get these sets of all the data in the database.
• The Jinq mini-ORM is intended only for queries of database data. It does not fully support updates of database data
• In the future, Jinq will be updated to support JPA2 POJO-style ORMs. When that happens, you will no longer need to generate entity objects from XML files as you do now.

Compile the sample demo program

• The code for the sample demo program is in the file demosrc/Main.java
• The sample runs some queries using the entities described in the previous step
• In the demo, Jinq is configured to not run the queries but simply show the discovered SQL queries on the console
• Be sure that ant uses Java 8 to compile the sample code

Run the demo

• Jinq-style queries are designed to mirror how you work with regular collections of Java objects
• When you want to query a collection of Java objects, you take a collection of Java objects, iterate over the objects, and find the ones you want.
• With Jinq, you can use the exact same procedure when querying a database
• Jinq allows you to use similar code to get a collection of database data, iterate over it, and find the ones you want
• To ensure that your queries are too verbose, Jinq uses Java 8's new functional syntax for iterating and filtering over data
• The code you write though is real Java code. You can actually run the code directly on small data sets and get the correct result. What Jinq does is that it translates your Java code into SQL queries that can be used to query large data sets
• Currently, Jinq offers query power similar to that of SQL92
• Check out the Query Guide for more information about how queries are written using Jinq

Running the demo with a real database

• The sample code can also be configured to actually run its queries against a real database
• Currently, the code can be configured to query an Apache Derby database.
• To do this, download the latest version of Apache Derby and put the jars derby.jar and derbytools.jar into the lib directory
• Then run ant RunDemoWithDb
• This command will
1. Create some database tables using derby by executing the SQL commands in demosrc/entities.sql
2. Run the demo but actually send the queries to the Derby database, logging the actual JDBC calls to the console (Note: this logging can be disabled)