com.github.vineey:rsql-querydsl-sort

= RSQL-QueryDSL

Author : John Michael Vincent S. Rustia +

ifdef::env-github[] image:https://api.travis-ci.org/vineey/archelix-rsql.svg?token%2FkdSmFoN3e8GGHqffx761["Build Status", link="https://travis-ci.org/vineey/archelix-rsql"] image:http://img.shields.io/:license-mit-blue.svg["License", link="https://github.com/vineey/archelix-rsql/blob/master/LICENSE.md"] image:https://coveralls.io/repos/github/vineey/archelix-rsql/badge.svg?branch=develop["Coverage Status", link="https://coveralls.io/github/vineey/archelix-rsql?branch=develop"] image:https://api.codacy.com/project/badge/grade/b119ffa40c674a18850c31ec3878c044["Codacy code quality", link="https://www.codacy.com/app/vinetech416/archelix-rsql"] image:https://maven-badges.herokuapp.com/maven-central/com.github.vineey/rsql-api-all/badge.svg["Maven Central", link="http://repo1.maven.org/maven2/com/github/vineey/rsql-api-all/"] endif::env-github[]

This library brings the convenience of SQL declarative nature to restful APIs in the form of RSQL but without the danger of sql injection by using a typesafe mapping of allowed field paths defined via integration with querydsl library. Like sql, it supports clauses such as select, filter, pagination and sorting that can easily be represented in http request parameters.

It primarily supports JPA model and MongoDB query via Querydsl. This is a small project but at its heart is dedicated to maintain highly cohesive and modular components. Contributions and suggestions are very much welcome and appreciated!

== QueryDSL API Modules

Rql specification used by this library is defined by this http://doc.apsstandard.org/2.1/spec/rql/[reference] and https://github.com/jirutka/rsql-parser[rsql-parser]. + Please see for more information about rql expressions.

• select - converts rql select expression into its querydsl projection equivalent
• filter - uses https://github.com/jirutka/rsql-parser[rsql-parser] library ast to convert filter string into its querydsl predicate equivalent
• page - converts rql limit expression into its querydsl pagination equivalent
• sort - converts rql sort expression into its querydsl sorting equivalent
• spring - provides integration with spring data such as pageable

== 1.0.0.RELEASE Notes Completes filter conversion to querydsl predicate. Completes sort and page conversion for rsql querydsl + Completes select conversion to querydsl projections. + Full support on Mongodb projection, filter, sort and page conversion. +

== 1.1.0 Milestones

• Add support for embeddable or nested Querydsl Paths
• Add support for JPA Association Paths (OneToMany, ManyToOne)

== 2.0.0 Milestones

Port rsql-querydsl v1.0.0.RELEASE code to v2.0.0 branch to be compatible with querydsl latest version v4.x.x. + 1.0.0.RELEASE and 2.0.0 will be simultaneous releases.

== 3.0.0 Milestones

• Support for rsql conversion to https://github.com/jOOQ/jOOQ[JOOQ] Library
• ?

== MAVEN

=== Bundled Rsql Querydsl Modules

You can get all rsql-querydsl modules via this dependency,

<dependency>
    <groupId>com.github.vineey</groupId>
    <artifactId>rsql-querydsl-all</artifactId>
    <version>1.0.0.RELEASE</version>
</dependency>

[source,groovy] [subs="attributes"]

dependencies { compile 'com.github.vineey:rsql-querydsl-all:1.0.0.RELEASE' }

=== Selective Rsql Querydsl Modules

or you can specify which module you only need by changing the artifactId by any of the ff:

• rsql-querydsl-select
• rsql-querydsl-filter
• rsql-querydsl-sort
• rsql-querydsl-page

such as [source,groovy] [subs="attributes"]

dependencies { compile 'com.github.vineey:rsql-querydsl-filter:1.0.0.RELEASE' }

To integrate with Spring Data Pageable, include this dependency,

[source,groovy] [subs="attributes"]

dependencies { compile 'com.github.vineey:rsql-querydsl-spring:1.0.0.RELEASE' }

=== Minimum JDK Required

• Java 8 (will try to support Java 7 in the next release by externalizing Java 8 DateTime converters)

=== Querydsl Integration Dependencies Required

• com.mysema.querydsl:querydsl-core:3.x.x or prior

=== Spring Integration Dependencies Required

• org.springframework.data:spring-data-commons:1.x.x or prior

== API DOCS

=== Querydsl Filter (rsql-querydsl-filter) Note: AOTM, this only supports first level fields of the entity or document. But will support embeddable pojo and other kinds of nested querydsl path.

Sample operators .... equals is == e.g. field == 'value' not equals is != e.g. field != 'value' like is =* startsWith e.g. field == 'value*' endsWith e.g. field == '*value' contains e.g. field == 'value' .... [source,java]

DefaultFilterParser filterParser = new DefaultFilterParser();

String rqlFilter = "employee.name == 'John'";

Map<String, Path> pathHashMap = ImmutableMap.<String, Path>builder() .put("employee.name", QEmployee.employee.name) .put("employee.age", QEmployee.employee.age) .put("employee.bday", QEmployee.employee.birthDate) .build();

Predicate predicate = filterParser.parse(rsqlFilter, withBuilderAndParam(new QuerydslFilterBuilder(), new QuerydslFilterParam() .setMapping(pathHashMap)));

//or a shorter version

Predicate predicate = filterParser.parse(rsqlFilter, withMapping(pathHashMap));

---

=== Querydsl Select Conversion (rsql-querydsl-select) Note: AOTM, this only supports first level fields of the entity or document. But will support embeddable pojo and other kinds of nested querydsl path.

[source,java]

//e.g. select(field1, field2,...) String rqlSelectExpression = "select(contact.company, contact.name, contact.age)"; DefaultSelectParser selectParser = new DefaultSelectParser(); Map<String, Path> mappings = ImmutableMap.<String, Path>builder() .put("contact.age", QContactDocument.contactDocument.age) .put("contact.name", QContactDocument.contactDocument.name) .put("contact.bday", QContactDocument.contactDocument.bday) .put("contact.company", QContactDocument.contactDocument.company) .build();

Expression projection = selectParser.parse(rqlSelectExpression, QuerydslSelectContext.withMapping(QContactDocument.contactDocument, mappings));

=== Querydsl Sort Conversion (rsql-querydsl-sort) Note: AOTM, this only supports first level fields of the entity or document. But will support embeddable pojo and other kinds of nested querydsl path.

[source,java]

//ascending is +, descending is - //e.g. sort(+field1, -field2,...) String sortExpression = "sort(+employeeNumber)";

DefaultSortParser sortParser = new DefaultSortParser();

Map<String, Path> mappings = ImmutableMap.<String, Path>builder() .put("employeeNumber", QEmployee.employee.employeeNumber) .build();

OrderSpecifierList orderSpecifierList = sortParser.parse(sortExpression, QuerydslSortContext.withMapping(mappings));

List orderSpecifiers = orderSpecifierList.getOrders();

=== Querydsl Page Conversion (rsql-querydsl-page)

[source,java]

//limit(, ) String rqlPage = "limit(10, 5)";

DefaultPageParser defaultPageParser = new DefaultPageParser();

QueryModifiers querydslPage = defaultPageParser.parse(rqlPage, withDefault());

or a simplified version

QuerydslPageParser querydslPageParser = new QuerydslPageParser();

QueryModifiers querydslPage = querydslPageParser.parse(rqlPage);

---

=== Bundled All Querydsl Modules (rsql-querydsl-all)

[source,java]

String rqlSelect = "select(contact.name, contact.age)"; String rqlFilter = "(contact.age =='1' and contact.name == 'A*') or (contact.age > '1' and contact.bday == '2015-05-05')"; String limit = "limit(0, 10)"; String sort = "sort(+contact.name)";

RqlInput rqlInput = new RqlInput() .setSelect(rqlSelect) .setFilter(rqlFilter) .setLimit(limit) .setSort(sort);

Map<String , Path> pathMapping = ImmutableMap.<String, Path>builder() .put("contact.name", QContactDocument.contactDocument.name) .put("contact.age", QContactDocument.contactDocument.age) .put("contact.bday", QContactDocument.contactDocument.bday) .build();

QuerydslMappingResult querydslMappingResult = querydslRqlParser.parse(rqlInput, new QuerydslMappingParam().setRootPath(QContactDocument.contactDocument).setPathMapping(pathMapping));

Expression selectExpression = querydslMappingResult.getProjection(); Predicate predicate = querydslMappingResult.getPredicate();

QueryModifiers querydslPage = querydslMappingResult.getPage();

List orderSpecifiers = querydslMappingResult.getOrderSpecifiers();

---

=== Integration of Querydsl to Spring Data Pageable

[source,java]

Pageable pageable = SpringUtil.toPageable(orderSpecifiers, querydslPage);

---

You can now use Expression, Predicate, QueryModifiers, OrderSpecifier or Pageable + in the Querydsl API, or in JPAQuery, + or in the Spring Data JPA/Mongo Repository.

=== A MORE APPROPRIATE WIKI To be follow!!!