Using Jinq with Scala (Deprecated)

Jinq can be used with Scala as well as with Java 8. With Jinq it's easy to use robust JPA-compliant object-relational mappers such as EclipseLink and Hibernate in your Scala projects without having to abandon the functional code style of Scala.

Jinq for Scala currently targets version 2.11 of Scala. It has not been tested with the Scala version 2.12. Due to the major changes in that version of Scala, Jinq may be incompatible with it.

Sample Code

The Jinq download comes with a sample Scala project that uses Jinq. You can compile and run the sample code by going into the sample-scala directory and using Scala's sbt to compile and run the program.

The Scala sample code mirrors the structure of the Java 8 sample code. The Java JPA entities and database initialization code are stored in the src/main/java directory. The Scala code for issuing queries against the in-memory database can be found in the src/main/scala directory.

The sample program runs a series of queries. For each query, it first prints the type of query it will run. Then it prints the actual JPQL database query that Jinq has constructed from the sample code and is executing. Finally, it prints out the results of the query.

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

Build

If you already have a Scala project that includes some JPA entities, you can add Jinq to your project by adding the jinq-jpa-scala dependency to your existing sbt or Maven build.

Set-Up

Jinq queries are written by taking streams of database data and filtering and transforming that data. To use Jinq when using JPA for database access, you need a way to get a Jinq stream of JPA data. You can do this with the org.jinq.jpa.JinqJPAScalaIteratorProvider class.

The JinqJPAScalaIteratorProvider's constructor normally takes a JPA EntityManagerFactory as a parameter. The JinqJPAScalaIteratorProvider is intended to be a singleton in your application that only needs to be created once.

val entityManagerFactory = 
  Persistence.createEntityManagerFactory("JPA");

val streams = new JinqJPAStreamProvider(
  entityManagerFactory);

In some cases, it is easier to get a reference to an EntityManager instead of an EntityManagerFactory. You can also create JinqJPAScalaIteratorProvider objects from an EntityManager whenever you want to perform a Jinq query although this is less efficient.

val streams = new JinqJPAScalaIteratorProvider(
  entityManager.getMetamodel());

Queries

Once you've created a JinqJPAScalaIteratorProvider, you can then use the streamAll() method to get a Jinq stream of JPA entities from a database. For example, if you have a Customer JPA entity and a JPA EntityManager called em, then you can get a stream of Customer objects from your database using the code below:

val customerStream = 
  streams.streamAll(em, classOf[Customer]);

Once you have this stream of entities, you can filter and transform it using the Jinq approach:

val customers = streams
  .streamAll(em, classOf[Customer])
  .where( c => c.getName() == "Bob" )
  .toList;

Jinq queries for Scala have behave similarly to Jinq queries for Java. More information about Jinq queries for Java is available in the query guide.

Differences

Here are the main differences between Jinq for Scala and Jinq for Java:

• The Scala version of Jinq uses Scala's tuples instead of Jinq's tuples.
• Jinq streams are Scala iterators instead of Java 8 streams
• You can use import org.jinq.orm.stream.scala.JinqConversions._ to automatically convert Java lists and collections into Jinq streams. This is useful when using 1:N JPA associations in queries.

Limitations

Here are some known limitations of the current implementation of Jinq for Scala:

• Because JPA is a Java object-relational mapping tool, it uses Java data types instead of Scala data types. For example, entity fields cannot have the type scala.math.BigDecimal but must use java.math.BigDecimal instead. For common types such as Int, Long, Double, and String, Scala will automatically hide any differences between the Scala type and the equivalent Java type.
• Currently, the Scala version of Jinq for JPA is configured so that if a query cannot be fully translated into a database query, it will throw an exception instead of trying to emulate its behavior.
• When passing variables into a query to be used as a parameter, these variables must be declared using val and not var.

  val param = "UK" // param must be a val, not a var
  val customers = streams
    .streamAll(em, classOf[Customer])
    .where( c => c.getCountry() == param )
    .toList

• When passing parameters through to subqueries, these parameters must be stored in val variables in the parent query.

  val param = "London"
  val customers = streams
    .streamAll(em, classOf[Country])
    .where( c => {
      val subparam = param;   // param is stored in a val
      c.getCities()
        .where( city => city.getName() == subparam )
        .count() > 0
    } )
    .toList

• Jinq creates database queries by translating the compiled bytecode of your program into queries. When doing comparisons using == in Scala, Scala outputs extra code for checking if the variables being compared are null. Since Jinq cannot tell whether these null checks were inserted by the programmer intentionally or whether Scala automatically inserted them, Jinq will conservatively include these NULL-checks in generated database queries. To avoid these extra checks, you can use equals() or eq for doing equality comparisons.
• When performing grouping operations, Scala's type inferencer is not able to determine the type of the grouping key. You must specify the type of the grouping key to Scala. For example, in the query below, the programmer must specify that the type of country is a String because Scala cannot infer the type from c.getCountry. In the future, we may try to provide a different grouping syntax for Scala that works better with Scala's type inferencing.

  streams.streamAll(em, classOf[City])
    .group(c => c.getCountry,
           (country: String, stream) => stream.count)
    .toList