Title: JEST Syntax ## 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): 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. ### Formal syntax: 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