JEST URI Syntax
JEST defines URI syntax to access persistent resources over HTTP.
As an example, to find a persistent Person instance with primary key 1234 and
receive the result in JSON format, an example URI would look like this (non functional URI):
http://www.example.com:8080/jest/find/format=json?type=Person&1234
The formal notation of a JEST URI is
URI := http://{host}[:port]/{context}/{action}[/qualifier]* [?argument] [&argument]*
The URI syntax rules, in the light of the above example, are as follows:
-
protocol is always http
-
host (www.example.com) and optional port number locates the
JEST servlet
-
context (jest) identifies the context path of the JEST servlet.
The context path is the servlet name
as specified in the web deployment descriptor for JEST servlet
-
action (find) is the first segment of the servlet path.
Allowed actions are find, query, domain, properties
etc.
-
zero or more qualifier may constitute the servlet path. Each
qualifier is separated by / character.
-
A qualifier must have a key and an optional value.
-
The qualifier key and value, if present, are separated by = sign.
-
A qualifier key is a valid Java identifier. The exact key is
conditional on the action. For example, find action
accepts format qualifier, query action accepts single,
named, maxResult, firstResult,
format as qualifiers.
In the example above, format=json qualifies that the response of
find action be formatted as JSON.
-
A qualifier may or may not have a value. For example, maxResult
qualifier for query action must have
an integer value while single qualifier does not.
-
zero or more argument may follow after the path by ? character.
-
each argument is separated by & character
-
An argument has an optional key and must have a value.
-
The argument key, if present, and value are separated by = sign.
-
some actions may enforce mandatory argument(s). For example, a find
action must have type argument
and at least one more argument for the primary key. A query action
must have q argument etc.
List of supported actions, qualifiers and arguments
The following sections tabulates the currently supported actions and
corresponding qualifiers and arguments.
A bold font denotes qualifier or argument as mandatory.
Action: find
Returns the result of a find() operation.
| qualifier-key | qualifier-value | Comment |
|---|
| format | xml or json | default is xml |
| plan | | name of one or more fetch
plan(s). Each name separated by comma character. |
| | | e.g.
find/plan=onlyBasicFields?type=Person&1234 |
| | | where onlyBasicFields is
name of a pre-defined Fetch Group |
| argument-key | argument-value | Comment |
|---|
| type | entity name | Fully-qualified Java class name or
alias of the entity |
| | primary key value | can be used for simple identity
without the id property name |
| | | e.g. /find?type=Person&1234 |
| id property | primary key value | Used for compound primary keys |
| | | e.g.
/find?type=Person&firstName=John&lastName=Doe |
Action : query
Returns the result of a Query.getResultList() or
Query.getSingleResult() operation.
| qualifier-key | qualifier-value | Comment |
|---|
| format | xml or json | default is xml |
| plan | | name of one or more fetch plan(s). Each
name separated by comma character. |
| single | | enforces single instance as query result
|
| | | e.g. {{/query/single?q=select p from
Person p where p.name=:x&x=John}} |
| named | | interprets the q argument value as a
named query |
| | | e.g.
/query/named?q=PersonByName&x=John |
| | | where PersonByName is named query
with x its named parameter |
| argument-key | argument-value | Comment |
|---|
| q | JPQL or Named Query | e.g. /query/named?q=AllPerson |
| | | or {{/query?q=select p from Person
p}} |
| | | e.g. {{/query?q=select p from
Person p where p.firstName=:x&x=John}} |
| bind parameter | parameter value | the values are converted to match
the target type |
| | | e.g. {{/query?q=select p from
Person p where p.gender=:g&g=MALE}} |
Action : domain
Returns the domain model in XML format.
Accepts no qualifier.
Accepts no argument.
Action : properties
Returns the configuration properties in HTML format.
Accepts no qualifier.
Accepts no argument.
URI := http://{host}[:port]/{context}/{action}[/qualifier]* [?argument][&argument]*
context := JEST servlet context root
action := find|query|domain|properties
qualifier := qualifier-key[=qualifier-value]
argument := [argument-key=] argument-value
qualifier-key := any valid Java identifier
qualifier-value := string
argument-key := string
argument-value := string
