Notice: This Wiki is now read only and edits are no longer 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"
Line 20: | Line 20: | ||
<tt>projectName</tt> | <tt>projectName</tt> | ||
| | | | ||
− | The name of the EclipseLink DBWS service. | + | The name of the EclipseLink DBWS-R service. |
| | | | ||
Yes | Yes | ||
Line 65: | Line 65: | ||
<tt>contextRoot</tt> | <tt>contextRoot</tt> | ||
| | | | ||
− | + | part of URI path context | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
| | | | ||
− | No | + | No |
| | | | ||
− | " / "+ <tt> | + | " / "+ <tt>JPA Persistence-Unit name</tt> |
|- | |- | ||
| | | | ||
<tt>dataSource</tt> | <tt>dataSource</tt> | ||
| | | | ||
− | JNDI datasource location | + | JNDI datasource location |
− | + | ||
| | | | ||
No | No | ||
| | | | ||
None | None | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
|- | |- | ||
| | | | ||
Line 107: | Line 87: | ||
| | | | ||
<tt>org.eclipse.persistence.platform.database.MySQLPlatform</tt> | <tt>org.eclipse.persistence.platform.database.MySQLPlatform</tt> | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
|- | |- | ||
| | | | ||
<tt>logLevel</tt> | <tt>logLevel</tt> | ||
| | | | ||
− | EclipseLink logging level | + | EclipseLink logging level - controls the amount and detail of log output by configuring the log level (in ascending order of information) to one of the following <tt>java.util.logging.Level</tt> values: |
− | + | ||
* <tt>off</tt> - Disable logging. | * <tt>off</tt> - Disable logging. | ||
* <tt>severe</tt> - Logs exceptions indicating EclipseLink cannot continue, as well as any exceptions generated during login. Includes a stack trace. | * <tt>severe</tt> - Logs exceptions indicating EclipseLink cannot continue, as well as any exceptions generated during login. Includes a stack trace. | ||
Line 155: | Line 105: | ||
<tt>info</tt> | <tt>info</tt> | ||
|- | |- | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
|} | |} | ||
Revision as of 09:20, 26 October 2011
DBWS Restful Component Design
The DBWS-R utility starts by reading some initial configuration information:
(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
dbws-builder.xml:
Property | Description | Required | Default |
---|---|---|---|
projectName |
The name of the EclipseLink DBWS-R service. |
Yes |
None |
username |
Database user name. |
Yes |
None |
password |
Database password. |
Yes |
None |
url |
Database connection URL. |
Yes |
None |
driver |
Class name of the JDBC driver. |
Yes |
None |
contextRoot |
part of URI path context |
No |
" / "+ JPA Persistence-Unit name |
dataSource |
JNDI datasource location |
No |
None |
platformClassname |
The fully qualified name of the EclipseLink database platform class to use to connect to the relational database. This class must be in the classpath. |
No |
org.eclipse.persistence.platform.database.MySQLPlatform |
logLevel |
EclipseLink logging level - controls the amount and detail of log output by configuring the log level (in ascending order of information) to one of the following java.util.logging.Level values:
|
No |
info |
- 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 </source> If the table name does not match the entity name, the user may specify an alias:
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:
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.metamodel
API):
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:
"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:
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