Skip to main content
Jump to: navigation, search

Difference between revisions of "Equinox/p2/Query Language for p2"

< Equinox‎ | p2
Line 7: Line 7:
 
When designing the language I tried to consider two things. Who is the primary user and which are the most common queries?
 
When designing the language I tried to consider two things. Who is the primary user and which are the most common queries?
  
 +
====Java style operators====
 
The primary user is typically well aqquinted with Java so I opted for using java operators such as '&&' and '||' rather then SQL'ish keywords like OR and AND. I also use '.' for member access and '[' ']' to get indexed access. The latter can also be used to get keyed access.
 
The primary user is typically well aqquinted with Java so I opted for using java operators such as '&&' and '||' rather then SQL'ish keywords like OR and AND. I also use '.' for member access and '[' ']' to get indexed access. The latter can also be used to get keyed access.
  
A large amount of queries involve versions, version ranges, and capability matching. So managing that is important. Another thing is to make sure the result of a query only contains the latest version of each found IU. I added a special keyword 'latest' to make that possible. A third thing that is important is to be able to support filtering based on ID's. This is now also built in to the language.
+
====Matches operator====
 +
A large amount of queries involve versions, version ranges, and capability matching. So managing that is important. Another thing is to make sure the result of a query only contains the latest version of each found IU. I added a special keyword 'latest' to make that possible. A third thing that is important is to be able to support filtering based on ID's. This is now also built in to the language through the matches operator '~='. It can be though of as the 'satisfies' method on an installable unit or provided capability, or as 'is included in' when used with a version and version range, or as a plain matches when used with a string and a pattern.
  
 +
====Combined queries====
 
It must also be possible to combine queries (hence && and ||).
 
It must also be possible to combine queries (hence && and ||).
  
 +
====Query parameters====
 
The query must be parameterised so that expression parsing can be done once and then executed multiple times.
 
The query must be parameterised so that expression parsing can be done once and then executed multiple times.
  
Line 20: Line 24:
 
Query for the latest IU of some specific id:
 
Query for the latest IU of some specific id:
 
<pre>latest id = :1</pre>
 
<pre>latest id = :1</pre>
Java code to query for the latest ID that matches a specific version range
+
Java code to query for the latest ID that matches a specific version range (not the matches operator):
<pre>IQuery query = queryFactory.createQuery("latest id = :1 and version ~= :2", id, range);</pre>
+
<pre>IQuery query = queryFactory.createQuery("latest id = :1 && version ~= :2", id, range);</pre>
 +
Java code to query for an ID that has a specific property set:
 +
<pre>IQuery query = queryFactory.createQuery("properties[:1] = :2", key, value);</pre>
 +
The same query, but this time for multiple possible values:
 +
<pre>IQuery query = queryFactory.createQuery("properties[:1] = ANY :2", key, new Object[] { v1, v2, v3 });</pre>
 +
Query for all categories found in the repository:
 +
<pre>IQuery query = queryFactory.createQuery("properties[:1] = 'true'", IInstallableUnit.PROP_TYPE_CATEGORY);</pre>
 +
Query for all IU's that fulfil at least one of the requirements from another IU.
 +
<pre>IQuery query = queryFactory.createQuery("ANY providedCapabilities ~= ANY :1", iu.getRequiredCapabilities());</pre>
  
 +
I think it would be valuable if users of p2 that have the need for specific queries could list them here. It is not unlikely that some queries might motivate some extension to the current syntax or to how the evaluator works.
  
 
===The [http://en.wikipedia.org/wiki/Backus%E2%80%93Naur_Form BNF]===
 
===The [http://en.wikipedia.org/wiki/Backus%E2%80%93Naur_Form BNF]===

Revision as of 10:51, 13 November 2009

Background

p2 has a query mechanism today that makes it very hard to create an implementation that is based on a database. It is also very hard to create an efficient client/server solution. The reason for this is that most of the queries are written as java code in a callback and there is often no good way to extract the semantics of the query.

We discussed this at length on the p2 meeting on November 9. This resulted in the bugzilla Create a QueryLanguage for p2. I've spend some time on this now and today I have a fully functional IQuery implementation.

Considerations

When designing the language I tried to consider two things. Who is the primary user and which are the most common queries?

Java style operators

The primary user is typically well aqquinted with Java so I opted for using java operators such as '&&' and '||' rather then SQL'ish keywords like OR and AND. I also use '.' for member access and '[' ']' to get indexed access. The latter can also be used to get keyed access.

Matches operator

A large amount of queries involve versions, version ranges, and capability matching. So managing that is important. Another thing is to make sure the result of a query only contains the latest version of each found IU. I added a special keyword 'latest' to make that possible. A third thing that is important is to be able to support filtering based on ID's. This is now also built in to the language through the matches operator '~='. It can be though of as the 'satisfies' method on an installable unit or provided capability, or as 'is included in' when used with a version and version range, or as a plain matches when used with a string and a pattern.

Combined queries

It must also be possible to combine queries (hence && and ||).

Query parameters

The query must be parameterised so that expression parsing can be done once and then executed multiple times.

Examples

Query for all IU's that has an id:

id = :1

Query for the latest IU of some specific id:

latest id = :1

Java code to query for the latest ID that matches a specific version range (not the matches operator):

IQuery query = queryFactory.createQuery("latest id = :1 && version ~= :2", id, range);

Java code to query for an ID that has a specific property set:

IQuery query = queryFactory.createQuery("properties[:1] = :2", key, value);

The same query, but this time for multiple possible values:

IQuery query = queryFactory.createQuery("properties[:1] = ANY :2", key, new Object[] { v1, v2, v3 });

Query for all categories found in the repository:

IQuery query = queryFactory.createQuery("properties[:1] = 'true'", IInstallableUnit.PROP_TYPE_CATEGORY);

Query for all IU's that fulfil at least one of the requirements from another IU.

IQuery query = queryFactory.createQuery("ANY providedCapabilities ~= ANY :1", iu.getRequiredCapabilities());

I think it would be valuable if users of p2 that have the need for specific queries could list them here. It is not unlikely that some queries might motivate some extension to the current syntax or to how the evaluator works.

The BNF

p2query : ('latest' | 'distinct')? orExpression ;

orExpression : andExpression ( '||' andExpression )* ;

andExpression : notExpression ( '&&' notExpression )* ;

notExpression
   : '!' notExpression
   | binaryExpression
   ;

op : '=' | '!=' | '>' | '>=' | '<' | '<=' | '~=' ;

binaryExpression : sideExpression op sideExpression ;

sideExpression : ('any' | 'all')? memberExpression ;

memberExpression : unaryExpression ( ( '.' ID ) | ( '[' memberExpression ']' ) )* ;

unaryExpression
   : '(' orExpression ')'
   | '[' memberExpression ( ',' memberExpression )* ']' // #array construct
   | '/' regexpPattern '/'
   | STRING
   | INT
   | parameter
   | 'self'
   | 'null'
   | 'true'
   | 'false'
   | ID // # implies self.identifier
   ;

   parameter
   : ':' INT
   ;

Back to the top