|
|
(15 intermediate revisions by the same user not shown) |
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}
| + | |
− | (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:
| + | |
− | </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 EclipseLink DBWS service.
| + | |
− | |
| + | |
− | Yes
| + | |
− | |
| + | |
− | None
| + | |
− | |-
| + | |
− | |
| + | |
− | <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>
| + | |
− | |
| + | |
− | The value of the <tt>web.xml</tt> file <tt>servlet-mapping</tt> element's <tt>url-pattern</tt> subelement:
| + | |
− | | + | |
− | <source lang="xml" enclose="div">
| + | |
− | Example:
| + | |
− | <servlet-mapping>
| + | |
− | ...
| + | |
− | <url-pattern>
| + | |
− | /servlet/MyWebService
| + | |
− | </url-pattern>
| + | |
− | </servlet-mapping>
| + | |
− | </source>
| + | |
− | |
| + | |
− | No
| + | |
− | |
| + | |
− | " / "+ <tt>projectName</tt>
| + | |
− | |-
| + | |
− | |
| + | |
− | <tt>dataSource</tt>
| + | |
− | |
| + | |
− | JNDI datasource location for the EclipseLink <tt>sessions.xml</tt> file.
| + | |
− | You must configure a JNDI data source before deploying your EclipseLink DBWS to a Java-EE server.
| + | |
− | |
| + | |
− | No
| + | |
− | |
| + | |
− | None
| + | |
− | |-
| + | |
− | |
| + | |
− | <tt>sessionsFileName</tt>
| + | |
− | |
| + | |
− | The name of EclipseLink <tt>sessions.xml</tt> file to add to the EclipseLink DBWS service archive file.
| + | |
− | |
| + | |
− | No
| + | |
− | |
| + | |
− | <tt>eclipselink-dbws-sessions.xml</tt>
| + | |
− | |-
| + | |
− | |
| + | |
− | <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>orSessionCustomizerClassName</tt>
| + | |
− | |
| + | |
− | The name of a Java class that implements the <code>eclipselink.persistence.config.SessionCustomizer</code> interface.
| + | |
− | The name is added to the EclipseLink <tt>sessions.xml</tt> file, allowing for customization of the object-relational mappings project.
| + | |
− | |
| + | |
− | No
| + | |
− | |
| + | |
− | None
| + | |
− | |-
| + | |
− | |
| + | |
− | <tt>oxSessionCustomizerClassName</tt>
| + | |
− | |
| + | |
− | The name of a Java class that implements the <code>eclipselink.persistence.config.SessionCustomizer</code> interface.
| + | |
− | The name is added to the EclipseLink <tt>sessions.xml</tt> file, allowing for customization of the object-XML mappings project.
| + | |
− | |
| + | |
− | No
| + | |
− | |
| + | |
− | None
| + | |
− | |-
| + | |
− | |
| + | |
− | <tt>wsdlLocationURI</tt>
| + | |
− | |
| + | |
− | The URI of this EclipseLink Database Web service's WSDL (used by Web service tools to generate the client code).
| + | |
− | |
| + | |
− | No
| + | |
− | |
| + | |
− | <tt>http://localhost:7001/projectName</tt>
| + | |
− | |-
| + | |
− | |
| + | |
− | <tt>logLevel</tt>
| + | |
− | |
| + | |
− | EclipseLink logging level to be inserted in the EclipseLink database Web service <tt>sessions.xml</tt> file.
| + | |
− | 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 EclipseLink cannot continue, as well as any exceptions generated during login. Includes a stack trace.
| + | |
− | * <tt>warning</tt> - Logs exceptions that do not force EclipseLink to stop, including all exceptions not logged with severe level. Does not include a stack trace.
| + | |
− | * <tt>info</tt> - Logs the login and logout per sever session, including the user name. After acquiring the session, detailed information is 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 trace.
| + | |
− | * <tt>finest</tt> - Includes additional low level information.
| + | |
− | |
| + | |
− | No
| + | |
− | |
| + | |
− | <tt>info</tt>
| + | |
− | |-
| + | |
− | |
| + | |
− | <tt>targetNameSpace</tt>
| + | |
− | |The URI of the target namespace that the EclipseLink Database Web service inserts into the <tt>eclipselink-dbws-schema.xsd</tt> file.
| + | |
− | |
| + | |
− | No
| + | |
− | |
| + | |
− | urn: + <tt>projectName</tt>
| + | |
− | |}
| + | |
− | | + | |
− | # 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 DBWS 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 DBWS 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/alias/employee/plural</nowiki>
| + | |
− | |PUT
| + | |
− | |update the <tt>alias.employee.plural</tt> property (201 Created)
| + | |
− | |-
| + | |
− | |<nowiki>/dbwsbuilder/meta/model</nowiki>
| + | |
− | |GET
| + | |
− | |retrieve the meta-model for the current project (200 OK)
| + | |
− | |-
| + | |
− | |<nowiki>/dbwsbuilder/meta/model/entities/</nowiki>
| + | |
− | |GET
| + | |
− | |retrieve the meta-data for all entities in the current project (200 OK)
| + | |
− | |-
| + | |
− | |<nowiki>/dbwsbuilder/meta/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 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
| + | |