Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "EclipseLink/Development/DBWS/RestfulComponent/Design"
< EclipseLink | Development | DBWS | RestfulComponent
| Line 1: | Line 1: | ||
__NOTOC__== DBRS Design == | __NOTOC__== DBRS Design == | ||
| − | The | + | The DBWS utility starts by reading some initial configuration information: |
<source lang="text" enclose="div"> | <source lang="text" enclose="div"> | ||
| − | prompt > | + | prompt > DBWSBuilder -REST [-builderFile {path to dbwsbuilder.properties}] -stageDir {path to stageDir} |
(if command-line arg -builderFile not present, default to look in current working directory) | (if command-line arg -builderFile not present, default to look in current working directory) | ||
| − | prompt > | + | prompt > DBWSBuilder running, connected to port 8884 ... Press <Return> to finish |
| − | + | dbwsbuilder.properties: | |
# builder properties | # builder properties | ||
| Line 31: | Line 31: | ||
alias.employee.tablename=EMP | alias.employee.tablename=EMP | ||
</source> | </source> | ||
| − | The | + | The DBWS utility will login in to the database using the given database credentials and 'scrape' the meta-data for the <tt>employee</tt> table: column names and datatypes, PKs, foreign-key relationships, etc. If the built-in pluralization does not generate acceptible URIs, the user can add an alias for that as well - e.g. if the entity is <i>person</i>, the plural should be <i>people</i>, not <i>persons</i>: |
<source lang="text" enclose="div"> | <source lang="text" enclose="div"> | ||
# project properties | # project properties | ||
| Line 37: | Line 37: | ||
</source> | </source> | ||
| − | The | + | The DBWS utility operates at two levels: |
| − | # it builds <b><i>RESTful</i></b> applications (see [[EclipseLink/Development/ | + | # it builds <b><i>RESTful</i></b> applications (see [[EclipseLink/Development/DBWS/RestfulComponent/RESTfulDesign|RESTful Design Principles]] for more details); and |
# it is <u>itself</u> a RESTful application that listens for messages that manipulate 'meta-resources', the in-memory representation of the meta-data for all entities in the project . This in-memory model is based on EclipseLink JAXB's OXM meta-data and EclipseLink JPA's ORM meta-data (which in turn is based upon the JPA2 <code>javax.persistence.metamodel</code> API):<br/>[[Image:JPA2Metamodel.png]]<br/> | # it is <u>itself</u> a RESTful application that listens for messages that manipulate 'meta-resources', the in-memory representation of the meta-data for all entities in the project . This in-memory model is based on EclipseLink JAXB's OXM meta-data and EclipseLink JPA's ORM meta-data (which in turn is based upon the JPA2 <code>javax.persistence.metamodel</code> API):<br/>[[Image:JPA2Metamodel.png]]<br/> | ||
| − | ===== | + | ===== DBWS Resource URI Design ===== |
At runtime, URIs for each resource (entity) can manipulate rows in the database as follows: | At runtime, URIs for each resource (entity) can manipulate rows in the database as follows: | ||
{|{{BMTableStyle}} | {|{{BMTableStyle}} | ||
| Line 107: | Line 107: | ||
|} | |} | ||
| − | ===== | + | ===== DBWS Meta-resources URI Design ===== |
| − | At design-time, the URIs for an entity's <i>meta-resources</i> can be manipulated. <br/>Note: all properties in <code> | + | At design-time, the URIs for an entity's <i>meta-resources</i> can be manipulated. <br/>Note: all properties in <code>dbwsbuilder.properties</code> are also available: |
{|{{BMTableStyle}} | {|{{BMTableStyle}} | ||
|-{{BMTHStyle}} | |-{{BMTHStyle}} | ||
| Line 115: | Line 115: | ||
! Result | ! Result | ||
|- | |- | ||
| − | |<nowiki>/ | + | |<nowiki>/dbwsbuilder/project/name</nowiki> |
|GET | |GET | ||
|retrieve the name of the current project (200 OK) | |retrieve the name of the current project (200 OK) | ||
|- | |- | ||
| − | |<nowiki>/ | + | |<nowiki>/dbwsbuilder/db/user</nowiki> |
|PUT | |PUT | ||
|update the <tt>db.user</tt> property (201 Created) | |update the <tt>db.user</tt> property (201 Created) | ||
|- | |- | ||
| − | |<nowiki>/ | + | |<nowiki>/dbwsbuilder/alias/employee/plural</nowiki> |
|PUT | |PUT | ||
|update the <tt>alias.employee.plural</tt> property (201 Created) | |update the <tt>alias.employee.plural</tt> property (201 Created) | ||
|- | |- | ||
| − | |<nowiki>/ | + | |<nowiki>/dbwsbuilder/meta/model</nowiki> |
|GET | |GET | ||
|retrieve the meta-model for the current project (200 OK) | |retrieve the meta-model for the current project (200 OK) | ||
|- | |- | ||
| − | |<nowiki>/ | + | |<nowiki>/dbwsbuilder/meta/model/entities/</nowiki> |
|GET | |GET | ||
|retrieve the meta-data for all entities in the current project (200 OK) | |retrieve the meta-data for all entities in the current project (200 OK) | ||
|- | |- | ||
| − | |<nowiki>/ | + | |<nowiki>/dbwsbuilder/meta/TBD</nowiki> |
|GET/PUT/POST/DELETE | |GET/PUT/POST/DELETE | ||
|TBD - figure out complete CRUD lifecycle for all parts of the meta-model | |TBD - figure out complete CRUD lifecycle for all parts of the meta-model | ||
| Line 141: | Line 141: | ||
|} | |} | ||
| − | ==== | + | ==== DBWS Plugin Design ==== |
| − | Once the meta-resources have been setup in their desired final state, the | + | Once the meta-resources have been setup in their desired final state, the DBWS utility will activate any and all plugins registered with the utility. These plugins will have read-only access to the meta-resources. If no plugins are specified, the default EclipseLink JPA+JAXB plugin will run. This plugin will examine the meta-resources and generate into the <tt>stageDir</tt> a deployable RESTful CRUD application for all specified entities. If desired, the default plugin can be overridden so that some other behaviour is activated. |
===== Example Plugins ===== | ===== Example Plugins ===== | ||
| Line 166: | Line 166: | ||
Other potential plugins could generate an HTML5-enabled Ajax/JFaces project to provide full graphical editing support for the entities. | Other potential plugins could generate an HTML5-enabled Ajax/JFaces project to provide full graphical editing support for the entities. | ||
| − | ===== | + | ===== DBWS Plugin API ===== |
| − | + | The information in the JPA metamodel is made available to plugins via an Abstract Syntax Tree | |
Revision as of 17:09, 25 October 2011
DBRS Design
The DBWS utility starts by reading some initial configuration information:
prompt > DBWSBuilder -REST [-builderFile {path to dbwsbuilder.properties}] -stageDir {path to stageDir}
(if command-line arg -builderFile not present, default to look in current working directory)
prompt > DBWSBuilder running, connected to port 8884 ... Press <Return> to finish
dbwsbuilder.properties:
# builder properties
builder.port=8884
#builder.mode=production
builder.mode=test
builder.test.port=8885
# project properties
project.name=myproject
project.entities=employee, other entities ...
# database properties
db.driver=com.mysql.jdbc.Driver
db.url=jdbc:mysql://localhost:3306/db
db.user=user
db.pwd=password
db.platform=org.eclipse.persistence.platform.database.MySQLPlatform
logging.level=info
(if command-line arg -builderFile not present, default to look in current working directory)
prompt > DBWSBuilder running, connected to port 8884 ... Press <Return> to finish
dbwsbuilder.properties:
# builder properties
builder.port=8884
#builder.mode=production
builder.mode=test
builder.test.port=8885
# project properties
project.name=myproject
project.entities=employee, other entities ...
# database properties
db.driver=com.mysql.jdbc.Driver
db.url=jdbc:mysql://localhost:3306/db
db.user=user
db.pwd=password
db.platform=org.eclipse.persistence.platform.database.MySQLPlatform
logging.level=info
If the table name does not match the entity name, the user may specify an alias:
# project properties
alias.employee.tablename=EMP
alias.employee.tablename=EMP
The DBWS utility will login in to the database using the given database credentials and 'scrape' the meta-data for the employee table: column names and datatypes, PKs, foreign-key relationships, etc. If the built-in pluralization does not generate acceptible URIs, the user can add an alias for that as well - e.g. if the entity is person, the plural should be people, not persons:
# project properties
alias.person.plural=people
alias.person.plural=people
The DBWS utility operates at two levels:
- it builds RESTful applications (see RESTful Design Principles for more details); and
- it is itself a RESTful application that listens for messages that manipulate 'meta-resources', the in-memory representation of the meta-data for all entities in the project . This in-memory model is based on EclipseLink JAXB's OXM meta-data and EclipseLink JPA's ORM meta-data (which in turn is based upon the JPA2
javax.persistence.metamodelAPI):
DBWS Resource URI Design
At runtime, URIs for each resource (entity) can manipulate rows in the database as follows:
| URI | Operation | Result | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| /myproject/entities/employees/ |
|
| ||||||||
| /myproject/entities/employees/count | GET with search modifier | retrieve a count of the list of employees (200 OK) | ||||||||
| /myproject/entities/employees/?pgNum=0&pgSize=40 | GET with query parameters | retrieve the first group of 40 employees (200 OK) Message body should include the following additional information:
| ||||||||
| /myproject/entities/employee/{id} |
|
|
DBWS Meta-resources URI Design
At design-time, the URIs for an entity's meta-resources can be manipulated.
Note: all properties in dbwsbuilder.properties are also available:
| URI | Operation | Result |
|---|---|---|
| /dbwsbuilder/project/name | GET | retrieve the name of the current project (200 OK) |
| /dbwsbuilder/db/user | PUT | update the db.user property (201 Created) |
| /dbwsbuilder/alias/employee/plural | PUT | update the alias.employee.plural property (201 Created) |
| /dbwsbuilder/meta/model | GET | retrieve the meta-model for the current project (200 OK) |
| /dbwsbuilder/meta/model/entities/ | GET | retrieve the meta-data for all entities in the current project (200 OK) |
| /dbwsbuilder/meta/TBD | GET/PUT/POST/DELETE | TBD - figure out complete CRUD lifecycle for all parts of the meta-model |
DBWS Plugin Design
Once the meta-resources have been setup in their desired final state, the DBWS utility will activate any and all plugins registered with the utility. These plugins will have read-only access to the meta-resources. If no plugins are specified, the default EclipseLink JPA+JAXB plugin will run. This plugin will examine the meta-resources and generate into the stageDir a deployable RESTful CRUD application for all specified entities. If desired, the default plugin can be overridden so that some other behaviour is activated.
Example Plugins
The GraphvizPlugin examines the meta-resources and using Graphviz, generate the following Entity-Relationship diagram:
digraph {
"Order Details"[shape=box];
"Orders"[shape=box];
"Products"[shape=box];
"Order Details" -> "Orders";
"Order Details" -> "Products";
}
"Order Details"[shape=box];
"Orders"[shape=box];
"Products"[shape=box];
"Order Details" -> "Orders";
"Order Details" -> "Products";
}
An alternative plugin - YumlmePlugin - uses the online website yuml.me to generate the following diagram:
http://yuml.me/diagram/scruffy/class/%5BCustomer%5D+1-%3E*%5BOrder%5D,%5BOrder%5D++1-items%3E*%5BLineItem%5D,%5BOrder%5D-0..1%5BPaymentMethod%5D.png
Other potential plugins could generate an HTML5-enabled Ajax/JFaces project to provide full graphical editing support for the entities.
DBWS Plugin API
The information in the JPA metamodel is made available to plugins via an Abstract Syntax Tree