|
|
(23 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 Plugin =====
| + | |
− | The GraphvizPlugin examines the meta-resources and using [http://http://www.graphviz.org Graphviz (open-source graph visualization software)], generat 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>
| + | |
− | <br/>
| + | |
− | [[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>
| + | |
− | <br/>
| + | |
− | [[Image:anotherSimpleERDiagram.png]]
| + | |
− | <br/>
| + | |