EclipseLink/Development/DBWS/RestfulComponent/Design

DBWS Restful Component 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 the table name does not match the entity name, the user may specify an alias:

# project properties
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

The DBWS utility operates at two levels:

1. it builds RESTful applications (see RESTful Design Principles for more details); and
2. 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/	GET PUT POST DELETE	retrieve list of employees (200 OK) replace list of employees (201 Created) add a new employee (201 Created) unused (400 Bad Request)
/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: pageNum: reflects the pgNum query parameter (or 0 for the default first page) pageSize: reflects the pgSz query parameter (or the default page size) itemsInPage: reflects the total number of employees in the current page totalItems: reflects the total number of employees
/myproject/entities/employee/{id}	GET PUT POST DELETE	retrieve employee details (200 OK | 404 Not Found) update employee details (201 Created | 404 Not Found) add a new employee (201 Created) remove employee (204 No Content | 404 Not Found)

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";
}

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