Showing posts with label Internal DSL. Show all posts
Showing posts with label Internal DSL. Show all posts

Wednesday, April 28, 2010

MongoDB with Sculptor - Repository

This post is part of a series of articles describing the support for MongoDB in Sculptor. This post explains how Repositories with useful operations are defined and how queries can be expressed in terms of the domain.

In the visualization of the blog sample you maybe noticed that there are Services with findById, findAll, save and delete even though they were not explicitly defined in the model. They come from that the domain objects are marked with with scaffold. That automatically generates some predefined CRUD operations in the Repository and corresponding Service.


Entity BlogPost {
scaffold
- Blog inBlog
String slug key
String title
String body
DateTime published nullable
Set<String> tags
- Author writtenBy
- List<Comment> comments opposite forPost
}


You can also define the needed operations explicitly like this:


Entity BlogPost {
- Blog inBlog
String slug key
String title
String body
DateTime published nullable
Set<String> tags
- Author writtenBy
- List<Comment> comments opposite forPost

Repository BlogPostRepository {
save;
delete;
findAll(PagingParameter pagingParameter);
findById;
findByKey;
List<@BlogPost> findPostsInBlog(@Blog blog);
List<@BlogPost> findPostsWithComments => AccessObject;
List<@BlogPost> findPostsWithTags(Set<String> tags);
protected findByCondition;
}


You don't need to do any manual coding for the built in operations, such as save, delete, findAll, findById, findByKey.
findByKey is for the natural key, i.e. the attributes marked with key (slug above).

There is good support for pagination and sorting.

As you see in the above sample it is also possible to define your own repository operations, such as findPostsWithTags.

findByCondition

The most interesting finder is findByCondition. Queries can expressed with an internal DSL that support code completion and refactoring. It is best illustrated with a few samples.


public List<BlogPost> findPostsInBlog(Blog blog) {
List<ConditionalCriteria> condition = criteriaFor(BlogPost.class)
.withProperty(inBlog()).eq(blog)
.orderBy(published()).descending()
.build();
return findByCondition(condition);
}



public List<BlogPost> findPostsWithGreatComments() {
List<ConditionalCriteria> condition = criteriaFor(BlogPost.class)
.withProperty(comments().title()).ignoreCaseLike(".*great.*")
.and().withProperty(published()).isNotNull()
.orderBy(published()).descending().build();
return findByCondition(condition);
}


The ConditionalCriteriaBuilder has support for defining queries with eq, like, between, lessThan, greaterThan, in, and, not, orderBy, and some more.

You can of course also work directly with the underlaying MongoDB DBCollection and DBObject for doing advanced queries that might not be supported by findByCondition.

Tuesday, December 1, 2009

Internal DSL for Criteria - part 3:3

In previous 2 articles I have described the basics of the new internal DSL for JPA/Hibernate criteria. Let us dive in to an advanced topic. We would like to be able to specify conditional expressions with logical operators, and with grouping of nested conditions.

// A and (B or C)
criteriaFor(Person.class).withProperty(aaa()).eq("A").and().lbrace()
.withProperty(bbb()).eq("B").or().withProperty(ccc()).eq("C").rbrace()
.build();


That should build a syntax tree like:

and
/ \
A or
/ \
B C


This means that I need to hold state of current and previous not completed operators in the builder. I hold the current operator in a stack and give braces a special meaning. The expression builder looks like this:


public class ConditionalCriteriaBuilder<T> {

private enum ExpressionOperator {
Not, Or, And, LBrace
}

private ConditionalCriteriaBuilder() {
}

public static <T> ConditionRoot<T> criteriaFor(Class<T> clazz) {
return new ConditionalCriteriaBuilder<T>().new RootBuilderImpl();
}

public interface ConditionRoot<T> {
List<ConditionalCriteria> build();
CondditionProperty<T> withProperty(Property<T> property);
ConditionRoot<T> and();
ConditionRoot<T> or();
ConditionRoot<T> not();
ConditionRoot<T> lbrace();
ConditionRoot<T> rbrace();
}

public interface CondditionProperty<T> {
ConditionRoot<T> eq(Object value);
}

public class RootBuilderImpl implements ConditionRoot<T> {
private final SimpleStack<ConditionalCriteria> criteriaStack = new SimpleStack<ConditionalCriteria>();
private final SimpleStack<ExpressionOperator> operatorStack = new SimpleStack<ExpressionOperator>();

/**
* End the expression with this build
*/
public List<ConditionalCriteria> build() {
return criteriaStack.asList();
}

public CondditionProperty<T> withProperty(Property<T> property) {
return new PropBuilderImpl(property.getName());
}

public ConditionRoot<T> and() {
operatorStack.push(ExpressionOperator.And);
return this;
}

public ConditionRoot<T> or() {
operatorStack.push(ExpressionOperator.Or);
return this;
}

public ConditionRoot<T> not() {
operatorStack.push(ExpressionOperator.Not);
return this;
}

public ConditionRoot<T> lbrace() {
operatorStack.push(ExpressionOperator.LBrace);
return this;
}

public ConditionRoot<T> rbrace() {
operatorStack.pop();
if (criteriaStack.isEmpty()) {
return this;
}
ConditionalCriteria lastCriteria = popCriteria();
pushCriteria(lastCriteria);
return this;
}

private ConditionalCriteria popCriteria() {
return criteriaStack.pop();
}

private void pushCriteria(ConditionalCriteria criteria) {
ExpressionOperator currentOperator = operatorStack.peek();
if (currentOperator == ExpressionOperator.Or || currentOperator == ExpressionOperator.And) {
ConditionalCriteria compositeCriteria;
if (currentOperator == ExpressionOperator.Or) {
compositeCriteria = ConditionalCriteria.or(popCriteria(), criteria);
} else {
compositeCriteria = ConditionalCriteria.and(popCriteria(), criteria);
}
criteriaStack.push(compositeCriteria);
operatorStack.pop();
} else if (currentOperator == ExpressionOperator.Not) {
ConditionalCriteria notCriteria = ConditionalCriteria.not(criteria);
criteriaStack.push(notCriteria);
operatorStack.pop();
if (!operatorStack.isEmpty() && !criteriaStack.isEmpty()) {
pushCriteria(criteriaStack.pop());
}
} else if (currentOperator == ExpressionOperator.LBrace) {
criteriaStack.push(criteria);
} else {
criteriaStack.push(criteria);
}
}

private class PropBuilderImpl implements CondditionProperty<T> {
String propertyName;

PropBuilderImpl(String name) {
this.propertyName = name;
}

public ConditionRoot<T> eq(Object value) {
pushCriteria(ConditionalCriteria.equal(propertyName, value));
return RootBuilderImpl.this;
}
}

}
}


The magic is in pushCriteria, which is invoked at the end of a condition, such as eq(), and also when right brace is reached. It is not a trivial problem, but thanks to the stack metaphor the solution is not that complicated.

A final thought about the syntax. Look at the expression again:

// A and (B or C)
criteriaFor(Person.class).withProperty(aaa()).eq("A").and().lbrace()
.withProperty(bbb()).eq("B").or().withProperty(ccc()).eq("C").rbrace()
.build();


I use special keywords for left brace and right brace. Why not use grouping with an single method instead and write the nested expression as method parameter?

// A and (B or C)
criteriaFor(Person.class).withProperty(aaa()).eq("A").and().group(
criteriaFor(Person.class).withProperty(bbb()).eq("B").or().withProperty(ccc()).eq("C"))
.buildSingle();


That would be possible, and probably easier to implement, but I see a few problems from end user perspective:
  1. There are already much clutter of braces due to the methods and it is hard to see and write the end brace of the group operation.
  2. You loose context and have to start the nested expression from scratch, i.e. with static criteriaFor method.

That was all of this exercise. I hope you find it useful as a practical example of how to develop a small Internal DSL. You find the full source code in subversion, including JUnit test.

Monday, November 30, 2009

Internal DSL for Criteria - part 2:3

In previous article I introduced the new internal DSL for JPA/Hibernate criteria. Let us look at how to handle the property names.

criteria().prop("lastName").eq("Svensson").build();
The problem with the above expression is that the property lastName is a String. Refactoring of Person.lastName will not be automatically detected. Another issue is that you have to remember/lookup that the property name is "lastName" when writing this expression, the IDE will not help you.

We, who are using Sculptor, define the domain object in the design model like this:

Entity Person {
String firstName
String lastName
}
From this Sculptor generates the Person class. We can also easily generate meta data of the properties of Person, which makes it possible to write expressions like this:

List<ConditionalCriteria> conditionalCriteria = ConditionalCriteriaBuilder.criteriaFor(Person.class)
.withProperty(PersonProperties.lastName()).eq("Svensson").build();
PersonProperties is generated and it contains static methods for each property, returning a Property<Person> object, which internally defines the strings. The builder is also parameterized, using the class defined in the criteriaFor factory method. This means that the withProperty method only accepts properties of correct type, i.e. Property<Person>.

Static imports can be used to make the expression more compact and readable:

import static org.fornax.cartridges.sculptor.framework.accessapi.ConditionalCriteriaBuilder.criteriaFor;
import static org.library.person.domain.PersonProperties.lastName;

List<ConditionalCriteria> conditionalCriteria = criteriaFor(Person.class)
.withProperty(lastName()).eq("Svensson").build();

Note that the eclipse keyboard shortcut for static import is <ctrl+shift+m> (mac: <cmd+shift+m>).

The expression builder looks like this:

public class ConditionalCriteriaBuilder<T> {

private final List<ConditionalCriteria> criteriaList = new ArrayList<ConditionalCriteria>();

private ConditionalCriteriaBuilder() {
}

public static <T> ConditionalCriteriaBuilder<T> criteriaFor(Class<T> clazz) {
return new ConditionalCriteriaBuilder<T>();
}

public List<ConditionalCriteria> build() {
return criteriaList;
}

private void addCriteria(ConditionalCriteria criteria) {
criteriaList.add(criteria);
}

public CondditionProperty<T> withProperty(Property<T> property) {
return new PropBuilderImpl(property.getName());
}

public interface CondditionProperty<T> {
ConditionalCriteriaBuilder<T> eq(Object value);
}

private class PropBuilderImpl implements CondditionProperty<T> {
String propertyName;

PropBuilderImpl(String name) {
this.propertyName = name;
}

public ConditionalCriteriaBuilder<T> eq(Object value) {
addCriteria(ConditionalCriteria.equal(propertyName, value));
return ConditionalCriteriaBuilder.this;
}
}
}


Alright, let us refactor the model, and introduce a BasicType for the first and last name of the Person:


Entity Person {
- @PersonName name
}

BasicType PersonName {
String first
String last
}


Generate, and you will immediately detect compilation error in the criteria expression. Fix it and it looks like this:

List<ConditionalCriteria> conditionalCriteria = criteriaFor(Person.class)
.withProperty(name().last()).eq("Svensson").build();


The generated Properties classes defines refererences also, so it easy to navigate associations with full code completion support. Great, our goals of code completion and refactoring are fulfilled.

That is not the end of this series of articles. In next article I will illustrate some more advanced operators that requires some intellectual thoughts. See you tomorrow.

Sunday, November 29, 2009

Internal DSL for Criteria - part 1:3

Hibernate has support for criteria queries and that is an awaited feature in JPA 2.0. The criteria API is rather technical and doesn't read to well with your domain terms, your DDD Ubiquitous Language. Therefore I have developed a small internal DSL in Java to be able to express conditional criteria in human readable format. It is not intended to handle everything in the criteria API.

I use this to illustrate how to implement an internal DSL. It is not hard once you have learned the tools to play with. Java is not optimal for DSLs, but let us use it as good as possible.

The goal was to create a fluent api that supported code completion and refactoring in a good way. A simple criteria may look like:

criteriaFor(Person.class).withProperty(sex()).eq(Gender.FEMALE).build();

and a more advanced criteria:

criteriaFor(Person.class)
.withProperty(sex()).eq(Gender.FEMALE).and()
.withProperty(ssn().country()).eq(SWEDEN).and()
.lbrace().withProperty(name().first()).like("A%")
.or().withProperty(name().last()).like("A%").rbrace()
.orderBy(name().last())
.build();
I will show how a few pieces of the DSL was developed. I have mostly used Expression Builder and Method Chaining, but also a few other tricks.

The expression builder doesn't create the JPA/Hibernate criteria directly. It creates an intermediate structure of objects , which can be translated to criteria API. The main reason for that is decoupling and possibility to have vendor specific implementations.

First, let me state the obvious: When developing an internal DSL it is perfect to do it the TDD way. You will add more and more features and do a lot of refactoring until you are satisfied with the language.

Enough of the introductory talking, let us go hands on to a simple equals expression:

List<ConditionalCriteria> conditionalCriteria =   
ConditionalCriteriaBuilder.criteria().prop("name").eq("Svensson").build();
This can be implemented in the builder as:

public class ConditionalCriteriaBuilder {
private final List<ConditionalCriteria> criteriaList = new ArrayList<ConditionalCriteria>();
private String propertyName;

private ConditionalCriteriaBuilder() {
}

public static ConditionalCriteriaBuilder criteria() {
return new ConditionalCriteriaBuilder();
}

public List<ConditionalCriteria> build() {
return criteriaList;
}

public ConditionalCriteriaBuilder prop(String name) {
propertyName = name;
return this;
}

public ConditionalCriteriaBuilder eq(Object value) {
addCriteria(ConditionalCriteria.equal(propertyName, value));
return this;
}

private void addCriteria(ConditionalCriteria criteria) {
criteriaList.add(criteria);
}
}

But that is not very good because it allows invalid expressions, such criteria().eq("A").prop("aaa").eq("B").

Therefore I introduce an interface for the property level:



public PropBuilder prop(String name) {
return new PropBuilderImpl(name);
}

public interface PropBuilder {
ConditionalCriteriaBuilder eq(Object value);
}

private class PropBuilderImpl implements PropBuilder {
String propertyName;

PropBuilderImpl(String name) {
this.propertyName = name;
}

public ConditionalCriteriaBuilder eq(Object value) {
addCriteria(ConditionalCriteria.equal(propertyName, value));
return ConditionalCriteriaBuilder.this;
}
}

This also facilitates code completion (ctrl+space) in a good way, which was one of our goals.

In next post, tomorrow, I will take care of the string property names that are not very refactoring friendly.