Getting Started (JPA)

1. The full Jinq distribution contains a sample project that demonstrates how to use Jinq. Download it and unpack it somewhere.
2. Jinq requires Java 8. Be sure you have the latest Java 8 JDK from Oracle installed.
3. The Jinq download contains a directory called sample with the sample project. The sample code for this program is in the sample/src directory.

Compiling the Sample Program

You must compile the sample code before running it. You can compile it using Maven, Ant, or manually.

Compile Using Maven

There is a Maven pom.xml in the sample directory. You can compile and execute the sample program using

mvn package exec:java

Compile Using Ant

There is an Ant build.xml build file in the sample directory. You can compile and execute the sample program using

ant

Compile Manually

You can compile the sample program from the command-line or using an IDE. Create a project, and include all the source code in the sample/src directory. Ensure that the .jar files in the sample/lib directory are in your classpath. Compile the project and then run the program defined by the class SampleMain.

Understanding the Sample Program

When run, the sample program does these things:

• It creates an in-memory SQL database with some sample data
• It connects to this database using JPA to map SQL tables to Java objects
• It runs some sample queries using Jinq

The code is laid out so that

• The SampleMain class in the default package contains the main query code. These queries are run by the runSampleQueries() method. For each query, Jinq will describe what information it is trying to find; then it will print out the JPQL query it has generated from the sample code; finally, it will print out the results returned by the query.
• The SampleDbCreator class creates the sample data for the in-memory SQL database.
• The JPA entities are defined in the package com.example.jinq.sample.jpa.entities. They define the mapping of SQL tables to Java objects. The mapping is compatible with JPA object-relational mapping tools like Hibernate or EclipseLink.

Below is the code for one of the queries in the sample program. It first prints out that it is running a query to find all the customers from the UK. It then executes the query. The query code gets all the customers from the database. It iterates over those customers and keeps only those where the Country field of the customer is equal to "UK". Finally, the results of the query are displayed on the screen.

out.println("CUSTOMERS FROM THE UK");

customers()
   .where(c -> c.getCountry().equals("UK"))
   
   .forEach( c -> 
      out.println(c.getName() + " " + c.getCountry()));

When the code is run, the sample code displays the text below on the screen. It says that it is looking for customers from the UK. It displays the database query that Jinq derived from the sample code and that it is using to find the results. Then it displays the results it found. The sample database only contains one customer from the UK, who is named Dave.

CUSTOMERS FROM THE UK
  SELECT A FROM Customer A WHERE A.country = 'UK'
Dave UK

Jinq Queries

• 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. To perform a query, you get a collection of database data, iterate over it, and find the ones you want
• To ensure that your queries aren't too verbose, Jinq uses Java 8's new functional syntax for iterating and filtering over data
• The code you write is real Java code. You can actually run the code directly on small data sets. Jinq does not run your code directly but translates your Java code into SQL queries.
• 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 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.
• 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
• Instructions about how to use Jinq with your existing JPA projects can be found in the documents Using Jinq with JPA ORMs and Using Jinq for JPA with Spring.