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.
Difference between revisions of "EclipseLink/UserGuide/DBWS/Overview/EclipseLink DBWSBuilder File (ELUG)"
m (→eclipselink-dbws-schema.xsd) |
m (→eclipselink-dbws-builder.xml) |
||
Line 216: | Line 216: | ||
==eclipselink-dbws-builder.xml== | ==eclipselink-dbws-builder.xml== | ||
− | The eclipselink-dbws-builder.xml file is used only with EclipseLink database Web services (see [[Introduction to EclipseLink (ELUG)#Considering EclipseLink Database Web Service Architecture|Considering EclipseLink Database Web Service Architecture]]). The EclipseLink database Web service command-line tool DBWSBuilder processes the elements described in this file to produce the requisite EclipseLink database Web services files (see [[#eclipselink-dbws.xml File] and [[#eclipselink-dbws-schema.xsd]]). | + | The eclipselink-dbws-builder.xml file is used only with EclipseLink database Web services (see [[Introduction to EclipseLink (ELUG)#Considering EclipseLink Database Web Service Architecture|Considering EclipseLink Database Web Service Architecture]]). The EclipseLink database Web service command-line tool DBWSBuilder processes the elements described in this file to produce the requisite EclipseLink database Web services files (see [[#|eclipselink-dbws.xml File|eclipselink-dbws.xml File]] and [[#eclipselink-dbws-schema.xsd|eclipselink-dbws-schema.xsd]]). |
The EclipseLink runtime uses the builder properties (see [[#Table 9-4|eclipselink-dbws-builder.xml File Elements (DBWSBuilder Properties]]) set in this file to determine such things as database connection URL, user name, password, session customizer class, and so forth, for a EclipseLink database Web service, as [[#Example 9-5|eclipselink-dbws-build.xml File]] shows. | The EclipseLink runtime uses the builder properties (see [[#Table 9-4|eclipselink-dbws-builder.xml File Elements (DBWSBuilder Properties]]) set in this file to determine such things as database connection URL, user name, password, session customizer class, and so forth, for a EclipseLink database Web service, as [[#Example 9-5|eclipselink-dbws-build.xml File]] shows. | ||
Line 299: | Line 299: | ||
JNDI datasource location to be inserted into the EclipseLink database Web service sessions.xml file (see sessionsFileName). | JNDI datasource location to be inserted into the EclipseLink database Web service sessions.xml file (see sessionsFileName). | ||
− | The JNDI name you use here is as defined in data-sources.xml file element managed-data-source attribute jndi-name or element native-data-source attribute jndi-name. | + | The JNDI name you use here is as defined in '''data-sources.xml''' file element managed-data-source attribute jndi-name or element native-data-source attribute jndi-name. |
− | You must configure this datasource before deploying your EclipseLink | + | You must configure this datasource before deploying your EclipseLink Database Web service. |
| | | | ||
No | No | ||
Line 310: | Line 310: | ||
sessionsFileName | sessionsFileName | ||
| | | | ||
− | The name of EclipseLink sessions.xml file to add to the EclipseLink | + | The name of EclipseLink sessions.xml file to add to the EclipseLink Database Web service service WAR file. |
| | | | ||
No | No | ||
Line 322: | Line 322: | ||
No | No | ||
| | | | ||
− | org.eclipse.persistence.platform.database.MySQLPlatform | + | '''org.eclipse.persistence.platform.database.MySQLPlatform''' |
|- | |- | ||
| | | | ||
orSessionCustomizerClassName | orSessionCustomizerClassName | ||
| | | | ||
− | The eclipselink.persistence.config.SessionCustomizer class name to add to the EclipseLink database Web service sessions.xml file. | + | The '''eclipselink.persistence.config.SessionCustomizer''' class name to add to the EclipseLink database Web service '''sessions.xml''' file. |
| | | | ||
No | No | ||
Line 336: | Line 336: | ||
oxSessionCustomizerClassName | oxSessionCustomizerClassName | ||
| | | | ||
− | The eclipse.persistence.config.SessionCustomzer class name to add to the EclipseLink | + | The '''eclipse.persistence.config.SessionCustomzer''' class name to add to the EclipseLink Database Web service '''sessions.xml''' file. |
| | | | ||
Line 346: | Line 346: | ||
wsdlLocationURI | wsdlLocationURI | ||
| | | | ||
− | The URI of this EclipseLink | + | The URI of this EclipseLink Database Web service's WSDL (used by Web Service tools to generate client code). |
| | | | ||
No | No | ||
| | | | ||
− | http://localhost:7001/projectName | + | <nowiki>http://localhost:7001/projectName</nowiki> |
|- | |- | ||
| | | | ||
Line 356: | Line 356: | ||
| | | | ||
EclipseLink logging level to be inserted in the EclipseLink database Web service sessions.xml file. | 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. | + | 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: |
− | Level values: | + | |
*off-Disable logging. | *off-Disable logging. | ||
*severe-Logs exceptions indicating EclipseLink cannot continue, as well as any exceptions generated during login. This includes a stack trace. | *severe-Logs exceptions indicating EclipseLink cannot continue, as well as any exceptions generated during login. This includes a stack trace. | ||
Line 373: | Line 372: | ||
| | | | ||
targetNameSpace | targetNameSpace | ||
− | |The URI of the target namespace that the EclipseLink | + | |The URI of the target namespace that the EclipseLink Database Web service inserts into the '''eclipselink-dbws-schema.xsd''' file. |
| | | | ||
No | No | ||
Line 414: | Line 413: | ||
For more information, see the following: | For more information, see the following: | ||
− | *[[#Creating Deployment Files for EclipseLink Database Web Services] | + | *[[#Creating Deployment Files for EclipseLink Database Web Services|Creating Deployment Files for EclipseLink Database Web Services]] |
− | *[#What You May Need to Know About Builder Operations] | + | *[[#What You May Need to Know About Builder Operations|What You May Need to Know About Builder Operations]] |
===What You May Need to Know About Builder Operations=== | ===What You May Need to Know About Builder Operations=== | ||
Line 456: | Line 455: | ||
*true - the operation returns information in the Simple XML Format. | *true - the operation returns information in the Simple XML Format. | ||
*false - the operation returns information in the Simple XML Format. | *false - the operation returns information in the Simple XML Format. | ||
− | For more information, see [[ | + | For more information, see [[EclipseLink/UserGuide/Creating_Deployment_Files_for_EclipseLink_Database_Web_Services_%28ELUG%29#Unstructured_Data|Unstructured Data]]. |
| | | | ||
false | false | ||
Line 464: | Line 463: | ||
| | | | ||
The name of the root-level Simple XML Format element-tag. | The name of the root-level Simple XML Format element-tag. | ||
− | For more information, see [[ | + | For more information, see [[EclipseLink/UserGuide/Creating_Deployment_Files_for_EclipseLink_Database_Web_Services_%28ELUG%29#Unstructured_Data|Unstructured Data]]. |
| | | | ||
<simple-xml-format> | <simple-xml-format> | ||
Line 472: | Line 471: | ||
| | | | ||
The name of the grouping XML element-tag for rows. | The name of the grouping XML element-tag for rows. | ||
− | For more information, see [[ | + | For more information, see [[EclipseLink/UserGuide/Creating_Deployment_Files_for_EclipseLink_Database_Web_Services_%28ELUG%29#Unstructured_Data|Unstructured Data]]. |
| | | | ||
<simple-xml> | <simple-xml> | ||
Line 487: | Line 486: | ||
| | | | ||
returnType | returnType | ||
− | |Specifies a return type when the operation's return type cannot be deduced from database metadata. Valid values are any type that the eclipselink-dbws-schema.xsd file defines. For more information, see [[#eclipselink-dbws-schema.xsd]]. | + | |Specifies a return type when the operation's return type cannot be deduced from database metadata. Valid values are any type that the '''eclipselink-dbws-schema.xsd''' file defines. For more information, see [[#eclipselink-dbws-schema.xsd|eclipselink-dbws-schema.xsd]]. |
Note: This attribute is optional. | Note: This attribute is optional. | ||
| | | |
Revision as of 10:36, 12 March 2009
Contents
eclipselink-dbws.xml File
The eclipselink-dbws.xml file is used only with EclipseLink database Web services (see Considering EclipseLink Database Web Service Architecture). The EclipseLink runtime uses the properties (see eclipselink-dbws.xml File Elements) set in this file to determine such things as service name, generated sessions.xml file name, and query definitions for a EclipseLink database Web service, as eclipselink-dbws.xml File shows.
eclipselink-dbws.xml File Elements
Element | Description | Required | Default |
---|---|---|---|
name |
The name of the EclipseLink database Web service. |
Yes-set by the DBWSBuilder property projectName. For more information, see DBWSBuilder and #eclipselink-dbws-builder.xml. |
None |
sessions-file |
The name of EclipseLink sessions.xml file to be used. |
No |
If not present, then eclipselink-dbws-sessions.xml will be used. |
Any of the following four operation elements:
|
One or more service operations. |
Yes |
None |
eclipselink-dbws.xml File
<?xml version="1.0" encoding="UTF-8"?> <dbws xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <name>example</name> <sessions-file>example-dbws-sessions.xml</sessions-file> <query> <name>countEmployees <result> <type>xsd:int</type> <simple-xml-format> <simple-xml-format-tag>employee-info <simple-xml-tag>aggregate-info </simple-xml-format> </result> <sql><![CDATA[select count(*) from EMP]]></sql> </query> <query> <name>findAllEmployees <result isCollection="true"> <type>empType</type> </result> <sql><![CDATA[select * from EMP]]></sql> </query> </dbws>
For more information, see the following:
XSD File Format
The eclipselink-dbws.xml file XSD is eclipselink-dbws_11_1_1.xsd and it is located in the <ECLIPSELINK_HOME>\xsds directory.
eclipselink-dbws-schema.xsd
The eclipselink-dbws-schema.xsd file is used only with EclipseLink database Web services (see Considering EclipseLink Database Web Service Architecture). A EclipseLink database Web service automatically generates this file from your database table metadata and uses it to derive element tag names and types.
An XML schema .xsd file is generated using the following two rules:
- table name: translate any characters not supported by XML, then convert to lower case (to_lowercase), and then add suffix Type. This will result in a top-level complex element type in the .xsd file.
- column name: translate characters, and then convert to lower case (to_lowercase). This will result in an element tag name. Note: This includes all columns, with BLOB columns being automatically mapped to xsd:base64Binary and, optionally, included in-line to the XML document, or handled as binary attachments (swaRef-style).
This table shows metadata from a typical database, and Corresponding eclipselink-dbws-schema.xsd shows the corresponding eclipselink-dbws-schema.xsd file that the EclipseLink database Web service generates from it.
Typical Database Metadata
OWNER | TABLE_NAME | COLUMN_NAME | DATA_TYPE | DATA_LENGTH | DATA_PRECISION | DATA_SCALE | NULLABLE | |
---|---|---|---|---|---|---|---|---|
align="left" | SCOTT | EMP | EMPNO | NUMBER | 22 | 4 | 0 | N |
SCOTT | EMP | ENAME | VARCHAR2 | 10 | (null) | (null) | Y | |
SCOTT | EMP | JOB | VARCHAR2 | 9 | (null) | (null) | Y | |
SCOTT | EMP | MGR | NUMBER | 22 | 4 | 0 | Y | |
SCOTT | EMP | IREDATE | DATE 7 | (null) | (null) | Y | ||
SCOTT | EMP | SAL | NUMBER | 22 | 7 | 2 | Y | |
SCOTT | EMP | COMM | NUMBER | 22 | 7 | 2 | Y | |
SCOTT |
EMP | DEPTNO | NUMBER | 22 | 2 | 0 | Y |
Corresponding eclipselink-dbws-schema.xsd
<?xml version="1.0" encoding="UTF-8"?> <xsd:schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" > <xsd:complexType name="empType"> <xsd:sequence> <xsd:element name="empno" type="xsd:int" xsi:nil="false"/> <xsd:element name="ename" type="xsd:string" xsi:nil="true"/> <xsd:element name="job" type="xsd:string" xsi:nil="true"/> <xsd:element name="mgr" type="xsd:int" minOccurs="0" xsi:nil="true"/> <xsd:element name="hiredate" type="xsd:dateTime" xsi:nil="true"/> <xsd:element name="sal" type="xsd:decimal" xsi:nil="true"/> <xsd:element name="comm" type="xsd:int" minOccurs="0" xsi:nil="true"/> <xsd:element name="deptno" type="xsd:int" xsi:nil="true"/> </xsd:sequence> </xsd:complexType> <xsd:element name="emp" type="empType"/> </xsd:schema>
For more information, see Creating Deployment Files for EclipseLink Database Web Services (ELUG)
eclipselink-dbws-builder.xml
The eclipselink-dbws-builder.xml file is used only with EclipseLink database Web services (see Considering EclipseLink Database Web Service Architecture). The EclipseLink database Web service command-line tool DBWSBuilder processes the elements described in this file to produce the requisite EclipseLink database Web services files (see eclipselink-dbws.xml File|eclipselink-dbws.xml File and eclipselink-dbws-schema.xsd).
The EclipseLink runtime uses the builder properties (see eclipselink-dbws-builder.xml File Elements (DBWSBuilder Properties) set in this file to determine such things as database connection URL, user name, password, session customizer class, and so forth, for a EclipseLink database Web service, as eclipselink-dbws-build.xml File shows.
eclipselink-dbws-builder.xml File Elements (DBWSBuilder Properties)
Element | Description | Required | Default |
---|---|---|---|
projectName |
The name of the EclipseLink database Web 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 sub-element. Example: <servlet-mapping> ... <url-pattern> /servlet/MyWebService </url-pattern> </servlet-mapping> |
No |
" / "+ projectName |
dataSource |
JNDI datasource location to be inserted into the EclipseLink database Web service sessions.xml file (see sessionsFileName). The JNDI name you use here is as defined in data-sources.xml file element managed-data-source attribute jndi-name or element native-data-source attribute jndi-name. You must configure this datasource before deploying your EclipseLink Database Web service. |
No |
None |
sessionsFileName |
The name of EclipseLink sessions.xml file to add to the EclipseLink Database Web service service WAR 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 eclipselink.persistence.config.SessionCustomizer class name to add to the EclipseLink database Web service sessions.xml file. |
No |
None |
oxSessionCustomizerClassName |
The eclipse.persistence.config.SessionCustomzer class name to add to the EclipseLink Database Web service sessions.xml file. |
No |
None |
wsdlLocationURI |
The URI of this EclipseLink Database Web service's WSDL (used by Web Service tools to generate 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:
|
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 |
eclipselink-dbws-build.xml File
<?xml version="1.0" encoding="UTF-8"?> <dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema" <properties> <property name="projectName">test</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> </properties> <table catalogPattern="%" schemaPattern="SCOTT" tableNamePattern="XR_EMP"> <procedure returnType="xr_empType" catalogPattern="SOME_PKG" schemaPattern="SCOTT" procedurePattern="GetEmployeeByEMPNO_DEPTNO"/> <sql name="findXREmpByName" isCollection="true" returnType="xr_empType"> <text> <![CDATA[select * from XR_EMP where ENAME like ?]]> </text> <binding name="ENAME" type="xsd:string"/> </sql> </table> <sql name="employeeInfo" simpleXMLFormatTag="employee-info" xmlTag="aggregate-counts" > <text> <![CDATA[select count(*) as "COUNT", max(SAL) as "MAX-Salary" from EMP]]> </text> </sql> </dbws-builder>
For more information, see the following:
- Creating Deployment Files for EclipseLink Database Web Services
- What You May Need to Know About Builder Operations
What You May Need to Know About Builder Operations
The following are the builder operations:
- procedure-You use this operation to specify a stored procedure.
- table-You use this operation to specify a database table.
- sql-You use to this operation to specify an SQL statement.
The following tables describe attributes of builder operations that eclipselink-dbws-build.xml File uses. This table lists attributes common to all three builder operations.
Common Attributes of Builder Operations
Attribute | Description | Default |
---|---|---|
name |
Name of the operation. |
None |
isCollection |
Specifies whether or not the procedure returns multiple results. The following are valid values:
|
false |
isSimpleXMLFormat |
Specifies whether or not the procedure returns information in the Simple XML Format (SXF). The following are valid values:
For more information, see Unstructured Data. |
false |
simpleXMLFormatTag |
The name of the root-level Simple XML Format element-tag. For more information, see Unstructured Data. |
<simple-xml-format> |
xmlTag |
The name of the grouping XML element-tag for rows. For more information, see Unstructured Data. |
<simple-xml> |
binaryAttachment |
Specifies whether or not the operation returns binary data as a SOAP attachment. The following are valid values:
|
false |
returnType |
Specifies a return type when the operation's return type cannot be deduced from database metadata. Valid values are any type that the eclipselink-dbws-schema.xsd file defines. For more information, see eclipselink-dbws-schema.xsd.
Note: This attribute is optional. |
None |
This table lists attributes of the procedure operation.
Attributes of the procedure Operation
Attribute | Description |
---|---|
catalogPattern |
A pattern that matches one or more catalog names in the database identified by the parent operation (supports SQL-92 % wild-card). |
schemaPattern |
A pattern that matches one or more schema names in the database identified by the parent operation (supports SQL-92 % wild-card). |
procedurePattern |
A pattern that matches one or more stored procedure, stored function, or stored trigger names in the database identified by the parent operation (supports SQL-92 % wild-card). |
This table lists attributes of the table operation.
Attributes of the table Operation
Attribute | Description |
---|---|
catalogPattern |
A pattern that matches one or more catalog names in the database identified by the parent operation (supports SQL-92 % wild-card). |
schemaPattern |
A pattern that matches one or more schema names in the database identified by the parent operation (supports SQL-92 % wild-card). |
tableNamePattern |
A pattern that matches one or more table names in the database identified by the parent operation (supports SQL-92 % wild-card). |