|
|
| (19 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| − | __NOTOC__== DBRS Design ==
| + | ignore |
| − | The DBRS utility starts by reading some initial configuration information:
| + | |
| − | <source lang="text" enclose="div">
| + | |
| − | prompt > DBRSBuilder [-builderFile {path to dbrsbuilder.properties}] -stageDir {path to stageDir}
| + | |
| − | (if command-line arg -builderFile not present, default to look in current working directory)
| + | |
| − | prompt > DBRSBuilder running, connected to port 8884 ... Press <Return> to finish
| + | |
| − | | + | |
| − | dbrsbuilder.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
| + | |
| − | </source>
| + | |
| − | If the table name does not match the entity name, the user may specify an alias:
| + | |
| − | <source lang="text" enclose="div">
| + | |
| − | # project properties
| + | |
| − | alias.employee.tablename=EMP
| + | |
| − | </source>
| + | |
| − | The DBRS 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">
| + | |
| − | # project properties
| + | |
| − | alias.person.plural=people
| + | |
| − | </source>
| + | |
| − | | + | |
| − | The DBRS utility operates at two levels:
| + | |
| − | # it builds <b><i>RESTful</i></b> applications (see [[EclipseLink/Development/DBRS/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/>
| + | |
| − | | + | |
| − | ===== DBRS Resource URI Design =====
| + | |
| − | At runtime, URIs for each resource (entity) can manipulate rows in the database as follows:
| + | |
| − | {|{{BMTableStyle}}
| + | |
| − | |-{{BMTHStyle}}
| + | |
| − | ! URI
| + | |
| − | ! Operation
| + | |
| − | ! Result
| + | |
| − | |-
| + | |
| − | | <nowiki>/myproject/entities/employees/</nowiki>
| + | |
| − | |
| + | |
| − | {|
| + | |
| − | |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)
| + | |
| − | |}
| + | |
| − | |-
| + | |
| − | | <nowiki>/myproject/entities/employees/count</nowiki>
| + | |
| − | | GET with search modifier
| + | |
| − | |retrieve a count of the list of employees (200 OK)
| + | |
| − | |-
| + | |
| − | | <nowiki>/myproject/entities/employees/?pgNum=0&pgSize=40</nowiki>
| + | |
| − | | GET with query parameters
| + | |
| − | |retrieve the first group of 40 employees (200 OK) <br/>
| + | |
| − | 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
| + | |
| − | |-
| + | |
| − | | <nowiki>/myproject/entities/employee/{id}</nowiki>
| + | |
| − | |
| + | |
| − | {|
| + | |
| − | |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)
| + | |
| − | |}
| + | |
| − | |}
| + | |
| − | | + | |
| − | ===== DBRS 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>dbrsbuilder.properties</code> are also available:
| + | |
| − | {|{{BMTableStyle}}
| + | |
| − | |-{{BMTHStyle}}
| + | |
| − | ! URI
| + | |
| − | ! Operation
| + | |
| − | ! Result
| + | |
| − | |-
| + | |
| − | |<nowiki>/dbrsbuilder/project/name</nowiki>
| + | |
| − | |GET
| + | |
| − | |retrieve the name of the current project (200 OK)
| + | |
| − | |-
| + | |
| − | |<nowiki>/dbrsbuilder/db/user</nowiki>
| + | |
| − | |PUT
| + | |
| − | |update the <tt>db.user</tt> property (201 Created)
| + | |
| − | |-
| + | |
| − | |<nowiki>/dbrsbuilder/alias/employee/plural</nowiki>
| + | |
| − | |PUT
| + | |
| − | |update the <tt>alias.employee.plural</tt> property (201 Created)
| + | |
| − | |-
| + | |
| − | |<nowiki>/dbrsbuilder/meta/model</nowiki>
| + | |
| − | |GET
| + | |
| − | |retrieve the meta-model for the current project (200 OK)
| + | |
| − | |-
| + | |
| − | |<nowiki>/dbrsbuilder/meta/model/entities/</nowiki>
| + | |
| − | |GET
| + | |
| − | |retrieve the meta-data for all entities in the current project (200 OK)
| + | |
| − | |-
| + | |
| − | |<nowiki>/dbrsbuilder/meta/TBD</nowiki>
| + | |
| − | |GET/PUT/POST/DELETE
| + | |
| − | |TBD - figure out complete CRUD lifecycle for all parts of the meta-model
| + | |
| − | |-
| + | |
| − | |}
| + | |
| − | | + | |
| − | ==== DBRS Plugin Design ====
| + | |
| − | Once the meta-resources have been setup in their desired final state, the DBRS 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 =====
| + | |
| − | The GraphvizPlugin examines the meta-resources and using [http://http://www.graphviz.org Graphviz], generate the following Entity-Relationship diagram:
| + | |
| − | <source lang="text" enclose="div">
| + | |
| − | digraph {
| + | |
| − | "Order Details"[shape=box];
| + | |
| − | "Orders"[shape=box];
| + | |
| − | "Products"[shape=box];
| + | |
| − | "Order Details" -> "Orders";
| + | |
| − | "Order Details" -> "Products";
| + | |
| − | }
| + | |
| − | </source>
| + | |
| − | [[Image:simpleERDiagram.gif]]
| + | |
| − | <br/>
| + | |
| − | An alternative plugin - YumlmePlugin - uses the online website [http://yuml.me yuml.me] to generate the following diagram:
| + | |
| − | <source lang="text" enclose="div">
| + | |
| − | 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
| + | |
| − | </source>
| + | |
| − | [[Image:anotherSimpleERDiagram.png]]
| + | |
| − | <br/>
| + | |
| − | | + | |
| − | Other potential plugins could generate an HTML5-enabled Ajax/JFaces project to provide full graphical editing support for the entities.
| + | |
| − | | + | |
| − | ===== DBRS Plugin API =====
| + | |
| − | TBD
| + | |
