|
|
| Line 1: |
Line 1: |
| − | __NOTOC__== DBWS Restful Component Design ==
| + | ignore |
| − | The DBWS-R utility starts by reading some initial configuration information:
| + | |
| − | <source lang="text" enclose="div">
| + | |
| − | prompt > DBWSBuilder -REST [-builderFile {path to dbws-builder.xml}] -stageDir {path to stageDir} ... additional options TBD
| + | |
| − | (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
| + | |
| − | </source>
| + | |
| − | | + | |
| − | Example <code>dbws-builder.xml:</code> file:
| + | |
| − | <source lang="xml" enclose="div">
| + | |
| − | <?xml version="1.0" encoding="UTF-8"?>
| + | |
| − | <dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema"
| + | |
| − | <properties>
| + | |
| − | <property name="projectName">myproject</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>
| + | |
| − | </source>
| + | |
| − | | + | |
| − | {| class="RuleFormalWideMax" dir="ltr" title="<b><code>DBWSBuilder</code> file Properties</b>" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
| + | |
| − | |- align="left" valign="top"
| + | |
| − | |+ <b><code>DBWSBuilder</code> builder xml file Properties</b>
| + | |
| − | ! id="r1c1-t2" align="left" valign="bottom" | '''Property'''
| + | |
| − | ! id="r1c2-t2" align="left" valign="bottom" | '''Description'''
| + | |
| − | ! id="r1c1-t2" align="left" valign="bottom" | '''Required'''
| + | |
| − | ! id="r1c2-t2" align="left" valign="bottom" | '''Default'''
| + | |
| − | |- align="left" valign="top"
| + | |
| − | | align="left" |
| + | |
| − | <tt>projectName</tt>
| + | |
| − | |
| + | |
| − | The name of the DBWS-R service.
| + | |
| − | |
| + | |
| − | Yes
| + | |
| − | |
| + | |
| − | None
| + | |
| − | |-
| + | |
| − | |
| + | |
| − | <tt>builder.mode</tt>
| + | |
| − | |
| + | |
| − | When DBWSBuilder is in <tt>test</tt> mode, it listens on the <tt>{$builder.test.port}</tt> for RESTful messages that manipulate the project's entities in a sandboxed environment (embedded Derby db). If DBWSBuilder is not in <tt>test</tt> mode, this property's value should be <tt>production</tt>
| + | |
| − | |
| + | |
| − | No
| + | |
| − | |
| + | |
| − | <tt>production</tt>
| + | |
| − | |-
| + | |
| − | |
| + | |
| − | <tt>builder.test.port</tt>
| + | |
| − | |
| + | |
| − | DBWSBuilder listens on this port for RESTful test messages
| + | |
| − | |
| + | |
| − | No
| + | |
| − | |
| + | |
| − | 8885
| + | |
| − | |-
| + | |
| − | |
| + | |
| − | <tt>builder.port</tt>
| + | |
| − | |
| + | |
| − | DBWSBuilder listens on this port for RESTful messages that manipulates project's meta-data.
| + | |
| − | |
| + | |
| − | No
| + | |
| − | |
| + | |
| − | 8884
| + | |
| − | |-
| + | |
| − | |
| + | |
| − | <tt>username</tt>
| + | |
| − | |
| + | |
| − | Database user name.
| + | |
| − | |
| + | |
| − | Yes
| + | |
| − | |
| + | |
| − | None
| + | |
| − | |-
| + | |
| − | |
| + | |
| − | <tt>password</tt>
| + | |
| − | |
| + | |
| − | Database password.
| + | |
| − | |
| + | |
| − | Yes
| + | |
| − | |
| + | |
| − | None
| + | |
| − | |-
| + | |
| − | |
| + | |
| − | <tt>url</tt>
| + | |
| − | |
| + | |
| − | Database connection URL.
| + | |
| − | |
| + | |
| − | Yes
| + | |
| − | |
| + | |
| − | None
| + | |
| − | |-
| + | |
| − | |
| + | |
| − | <tt>driver</tt>
| + | |
| − | |
| + | |
| − | Class name of the JDBC driver.
| + | |
| − | |
| + | |
| − | Yes
| + | |
| − | |
| + | |
| − | None
| + | |
| − | |-
| + | |
| − | |
| + | |
| − | <tt>contextRoot</tt>
| + | |
| − | |
| + | |
| − | part of URI path context
| + | |
| − | |
| + | |
| − | No
| + | |
| − | |
| + | |
| − | " / " + <tt>projectname</tt> (value of {$projectName} property as lowercase)
| + | |
| − | |-
| + | |
| − | |
| + | |
| − | <tt>dataSource</tt>
| + | |
| − | |
| + | |
| − | JNDI datasource location
| + | |
| − | |
| + | |
| − | No
| + | |
| − | |
| + | |
| − | None
| + | |
| − | |-
| + | |
| − | |
| + | |
| − | <tt>platformClassname</tt>
| + | |
| − | |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
| + | |
| − | |
| + | |
| − | <tt>org.eclipse.persistence.platform.database.MySQLPlatform</tt>
| + | |
| − | |-
| + | |
| − | |
| + | |
| − | <tt>logLevel</tt>
| + | |
| − | |
| + | |
| − | 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>severe</tt> - Logs exceptions indicating the DBWS-R application cannot continue, as well as any exceptions generated during login. Includes a stack trace.
| + | |
| − | * <tt>warning</tt> - Logs exceptions that do not force the DBWS-R application to stop, including all exceptions not logged with severe level. Does not include a stack trace.
| + | |
| − | * <tt>info</tt> - Logs the database login (and logout), including the user name. After login, some additional detailed information may be logged.
| + | |
| − | * <tt>config</tt> - Logs only login, JDBC connection, and database information.
| + | |
| − | * <tt>fine</tt> - Logs SQL.
| + | |
| − | * <tt>finer</tt> - Similar to warning. Includes stack traces.
| + | |
| − | * <tt>finest</tt> - Includes additional low level information.
| + | |
| − | |
| + | |
| − | No
| + | |
| − | |
| + | |
| − | <tt>info</tt>
| + | |
| − | |-
| + | |
| − | |}
| + | |
| − | | + | |
| − | If the table name does not match the entity name, the user may specify an alias:
| + | |
| − | <source lang="xml" enclose="div">
| + | |
| − | <?xml version="1.0" encoding="UTF-8"?>
| + | |
| − | <dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema"
| + | |
| − | <properties>
| + | |
| − | <property name="projectName">myproject</property>
| + | |
| − | ... additional properties ...
| + | |
| − | </properties>
| + | |
| − | <entities>
| + | |
| − | <entity tablename="EMP">employee</entity>
| + | |
| − | ...
| + | |
| − | </source>
| + | |
| − | The DBWS-R 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="xml" enclose="div">
| + | |
| − | <?xml version="1.0" encoding="UTF-8"?>
| + | |
| − | <dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema"
| + | |
| − | <properties>
| + | |
| − | <property name="projectName">myproject</property>
| + | |
| − | ... additional properties ...
| + | |
| − | </properties>
| + | |
| − | <entities>
| + | |
| − | <entity plural="people">person</entity>
| + | |
| − | ...
| + | |
| − | </source>
| + | |
| − | The DBWS-R utility operates at two levels:
| + | |
| − | # it builds <b><i>RESTful</i></b> applications (see [[EclipseLink/Development/DBWS/RestfulComponent/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/>
| + | |
| − | | + | |
| − | ===== DBWS 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)
| + | |
| − | |}
| + | |
| − | |}
| + | |
| − | | + | |
| − | ===== DBWS 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>dbwsbuilder.properties</code> are also available:
| + | |
| − | {|{{BMTableStyle}}
| + | |
| − | |-{{BMTHStyle}}
| + | |
| − | ! URI
| + | |
| − | ! Operation
| + | |
| − | ! Result
| + | |
| − | |-
| + | |
| − | |<nowiki>/dbwsbuilder/project/name</nowiki>
| + | |
| − | |GET
| + | |
| − | |retrieve the name of the current project (200 OK)
| + | |
| − | |-
| + | |
| − | |<nowiki>/dbwsbuilder/db/user</nowiki>
| + | |
| − | |PUT
| + | |
| − | |update the <tt>db.user</tt> property (201 Created)
| + | |
| − | |-
| + | |
| − | |<nowiki>/dbwsbuilder/employee/plural</nowiki>
| + | |
| − | |PUT
| + | |
| − | |update the <tt>plural</tt> attribute (201 Created)
| + | |
| − | |-
| + | |
| − | |<nowiki>/dbwsbuilder/info</nowiki>
| + | |
| − | |GET
| + | |
| − | |retrieve the meta-model for the current project (200 OK)
| + | |
| − | |-
| + | |
| − | |<nowiki>/dbwsbuilder/info/entity/employee/</nowiki>
| + | |
| − | |GET
| + | |
| − | |retrieve the meta-data for the employee entity in the current project (200 OK)
| + | |
| − | |-
| + | |
| − | |<nowiki>/dbwsbuilder/info/TBD</nowiki>
| + | |
| − | |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 <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.
| + | |
| − | | + | |
| − | ===== DBWS Plugin API =====
| + | |
| − | The information in the JPA metamodel is made available to plugins via an Abstract Syntax Tree
| + | |
