Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "EclipseLink/Development/DBWS/RestfulComponent/Design"

Line 1: Line 1:
 
__NOTOC__== DBWS Restful Component Design ==
 
__NOTOC__== DBWS Restful Component Design ==
−
The DBWS utility starts by reading some initial configuration information:
+
The DBWS-R utility starts by reading some initial configuration information:
 
<source lang="text" enclose="div">
 
<source lang="text" enclose="div">
−
prompt > DBWSBuilder -REST [-builderFile {path to dbwsbuilder.properties}] -stageDir {path to stageDir}
+
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)
 
         (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
 
prompt > DBWSBuilder running, connected to port 8884 ... Press <Return> to finish
  
−
dbwsbuilder.properties:
+
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 properties

Revision as of 09:16, 26 October 2011

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:
DBWSBuilder builder xml file Properties
Property Description Required Default

projectName

The name of the EclipseLink DBWS service.

Yes

None

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

The value of the web.xml file servlet-mapping element's url-pattern subelement:

Example:
<servlet-mapping>
    ...
    <url-pattern>
        /servlet/MyWebService
    </url-pattern>
</servlet-mapping>

No

" / "+ projectName

dataSource

JNDI datasource location for the EclipseLink sessions.xml file. You must configure a JNDI data source before deploying your EclipseLink DBWS to a Java-EE server.

No

None

sessionsFileName

The name of EclipseLink sessions.xml file to add to the EclipseLink DBWS service archive file.

No

eclipselink-dbws-sessions.xml

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

orSessionCustomizerClassName

The name of a Java class that implements the eclipselink.persistence.config.SessionCustomizer interface. The name is added to the EclipseLink sessions.xml file, allowing for customization of the object-relational mappings project.

No

None

oxSessionCustomizerClassName

The name of a Java class that implements the eclipselink.persistence.config.SessionCustomizer interface. The name is added to the EclipseLink sessions.xml file, allowing for customization of the object-XML mappings project.

No

None

wsdlLocationURI

The URI of this EclipseLink Database Web service's WSDL (used by Web service tools to generate the client code).

No

http://localhost:7001/projectName

logLevel

EclipseLink logging level to be inserted in the EclipseLink database Web service sessions.xml file. 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

targetNameSpace

The URI of the target namespace that the EclipseLink Database Web service inserts into the eclipselink-dbws-schema.xsd file.

No

urn: + projectName

  1. builder properties

builder.port=8884

  1. builder.mode=production

builder.mode=test builder.test.port=8885

  1. project properties

project.name=myproject project.entities=employee, other entities ...

  1. 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:

# project properties
alias.employee.tablename=EMP

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

# project properties
alias.person.plural=people

The DBWS 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):
    JPA2Metamodel.png
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 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";
}

SimpleERDiagram.gif
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

AnotherSimpleERDiagram.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

Retrieved from "https://wiki.eclipse.org/index.php?title=EclipseLink/Development/DBWS/RestfulComponent/Design&oldid=274539"

Back to the top