Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
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 | + | 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 | ||
− | + | 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:
(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:
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 |
No |
None |
oxSessionCustomizerClassName |
The name of a Java class that implements the |
No |
None |
wsdlLocationURI |
The URI of this EclipseLink Database Web service's WSDL (used by Web service tools to generate the client code). |
No |
|
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:
|
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 |
- 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:
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:
alias.person.plural=people
The DBWS utility operates at two levels:
- it builds RESTful applications (see RESTful Design Principles for more details); and
- 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):
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/ |
|
| ||||||||
/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:
| ||||||||
/myproject/entities/employee/{id} |
|
|
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:
"Order Details"[shape=box];
"Orders"[shape=box];
"Products"[shape=box];
"Order Details" -> "Orders";
"Order Details" -> "Products";
}
An alternative plugin - YumlmePlugin - uses the online website yuml.me to generate the following diagram:
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