Page History

JEST

...

URI Syntax

JEST defines URI syntax to access persistent resources over HTTP.

For example, to find a persistent Person instance with primary key 1234 and receive the result in JSON format will be:

...

http://www.

...

example.com:8080/jest

...

Panel

titleBGColor	#F7D6C1
title	List the key-value properties of the persistent unit

http://www.jpa.com/jest/properties^{Image Removed}

Panel

titleBGColor	#F7D6C1
title	Find an instance by simple key

http://www.jpa.com/jest/find?type=Person&123456789^{Image Removed}

Panel

titleBGColor	#F7D6C1
title	Find an instance by compound key

http://www.jpa.com/jest/find?type=Person&ssn=123456789&name=John^{Image Removed}

Panel

titleBGColor	#F7D6C1
title	Query with no parameter

http://www.jpa.com/jest/query?q=select^{Image Removed} p from Person p

Panel

titleBGColor	#F7D6C1
title	Query with single parameter

http://www.jpa.com/jest/query?q=select^{Image Removed} p from Person p where p.name=:name&name=John

Panel

titleBGColor	#F7D6C1
title	Query with multiple parameters

http://www.jpa.com/jest/query?q=select^{Image Removed} p from Person p where p.name=:name and age > :age&name=John&age=20

...

titleBGColor	#F7D6C1
title	Query for single result

...

/find/format=json?type=Person&1234^{Image Added}

The formal notation of a JEST URI is

Code Block
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

...

titleBGColor	#F7D6C1
title	Get the result of the named query

...

	interprets the q argument value as a named query
		e.g. `/query/named?q=`

...

PersonByName&

...

x=John

...

titleBGColor	#F7D6C1
title	Get the single result of the named query

http://www.jpa.com/jest/query/single/named?q=QueryPersonByName&name=John^{Image Removed}

or

...


		where `PersonByName` is named query with `x` its named parameter

argument-key	argument-value	Comment
q	JPQL or Named Query	e.g. `/query?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:

Code Block
URI

Panel

titleBGColor	#F7D6C1
title	Get first 20 rows of query using a fetch plan

http://www.jpa.com/jest/query/fecthplan=myPlan/ignoreCache/maxResult=20?q=select^{Image Removed} p from Person p

Code Block

title	URI syntax for JEST


   uri := http://{host}[:port]/{context}/{action}[/[qualifier]* ['?'argument][parameter&argument]'&'*]

   *

Code Block


context   := JEST servlet context root
action    := find|query|domain|properties
qualifier := qualifier-key['='qualifier-value]
 argument  parameter := parameter[argument-key'='parameter-value 
   
   action    : denotes the JPA operation to be performed.
               For example, find, query, insert, merge, remove, properties, domain etc.

   qualifier : qualifies the action. 
               specific to the action, e.g. a query action can qualify with query/single to get a single result as in above ex09.
               zero or more qualifier can be specified. 
               qualifier may have value separated by '='  
               each qualifier is separated by '/' 
               qualifier ordering is not significant (see above ex11.1 and ex11.2)
            
   parameter  : parameter for the action
            For example, JPQL string is a parameter for a query action
            zero or more parameter can be specified
            parameter may have value separated by '='
            each parameter is separated by '&' 
            first parameter can have special semantics based on action, e.g. first parameter for 'query' is JPQL string, 
            or first parameter for 'find' is the entity name, etc.]argument-value
qualifier-key := any valid Java identifier 
qualifier-value := string
argument-key   := string 
argument-value := string

Child pages

Versions Compared

Old Version 3

New Version 4

Key

JEST

URI Syntax

List of supported actions, qualifiers and arguments

Action: find

Action : query

Action : domain

Action : properties

Formal syntax: