EclipseLink/Development/DBWS/RestfulComponent/Design

DBWS Restful Component Design

The DBWS-R utility starts by reading some initial configuration information:

prompt > DBWSBuilder -REST [-builderFile {path to dbws-builder.xml}] -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

dbws-builder.xml:

Example DBWSBuilder builder xml file:

<?xml version="1.0" encoding="UTF-8"?>
<dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   <properties>
        <property name="projectName">test</property>
        <property name="driver">oracle.jdbc.OracleDriver</property>
        <property name="password">tiger</property>
        <property name="url">jdbc:oracle:thin:@localhost:1521:ORCL</property>
        <property name="username">scott</property>
        ... additional properties ...
    </properties>
    <entities>
      <entity>employee</entity>
      <entity>another_entity</entity>
      <entity>yet_another_entity</entity>
    </entities>
</dbws-builder>

DBWSBuilder builder xml file Properties

Property	Description	Required	Default
projectName	The name of the EclipseLink DBWS-R service.	Yes	None
builder.mode	When DBWSBuilder is in test mode, it listens on the {$builder.test.port} for RESTful messages that manipulate the project's entities in a sandboxed environment (embedded Derby db)	No	test or production
builder.test.port=8885	DBWSBuilder listens on this port for RESTful test messages	No	8885
builder.port	DBWSBuilder listens on this port for RESTful messages that manipulates project's meta-data.	No	8884
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: off - Disable logging. severe - Logs exceptions indicating EclipseLink cannot continue, as well as any exceptions generated during login. Includes a stack trace. warning - Logs exceptions that do not force EclipseLink to stop, including all exceptions not logged with severe level. Does not include a stack trace. info - Logs the login and logout per sever session, including the user name. After acquiring the session, detailed information is logged. config - Logs only login, JDBC connection, and database information. fine - Logs SQL. finer - Similar to warning. Includes stack trace. finest - Includes additional low level information.	No	info

If the table name does not match the entity name, the user may specify an alias:

<?xml version="1.0" encoding="UTF-8"?>
<dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   <properties>
        <property name="alias.employee.tablename">EMP</property>

The DBWS-R 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:

<?xml version="1.0" encoding="UTF-8"?>
<dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   <properties>
        <property name="alias.person.plural">people</property>

The DBWS-R 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-R 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