Jump to: navigation, search

Difference between revisions of "EclipseLink/UserGuide/DBWS/Overview/EclipseLink DBWSBuilder File (ELUG)"

m (eclipselink-dbws.xml File)
m (Replacing page with 'For EclipseLink DBWS documentation,including JAX-WS and JAX-RS, see http://www.eclipse.org/eclipselink/dbws.php Category: EclipseLink User's Guide [[Category: Release 1.1]...')
 
(43 intermediate revisions by 3 users not shown)
Line 1: Line 1:
== eclipselink-dbws.xml File ==
+
For EclipseLink DBWS documentation,including JAX-WS and JAX-RS, see http://www.eclipse.org/eclipselink/dbws.php
The eclipselink-dbws.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 runtime uses the properties (see [[#Table 9–2]]) 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 [[#Example 9–3]] shows.
+
 
+
'''''eclipselink-dbws.xml File Elements'''''
+
<span id="Table 9-2"></span>
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="eclipselink-dbws.xml File Elements." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t2" align="left" valign="bottom" | '''Element'''
+
! 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" |
+
name
+
|
+
The name of the EclipseLink database Web service.
+
|
+
Yes-set by the DBWSBuilder property projectName. For more information, see Section [[#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:
+
*insert
+
*update
+
*delete
+
*query
+
|
+
One or more service operations.
+
|
+
Yes
+
|
+
None
+
|}
+
 
+
<span id="Example 9-3"></span>
+
 
+
'''''eclipselink-dbws.xml File'''''
+
 
+
<source lang="xml">
+
 
+
<?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>
+
</source>
+
 
+
For more information, see the following:
+
*[[Creating Deployment Files for EclipseLink Database Web Services (ELUG)]]
+
*[[Creating Deployment Files for EclipseLink Database Web Services (ELUG)#DBWSBuilder|DBWSBuilder]]
+
 
+
===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 Section 2.18, "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:
+
<ol>
+
<li>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.
+
 
+
Note
+
The algorithm for translating characters not supported by XML is identical to the one used by Oracle XML-SQL utility (see XML-SQL Utility (XSU) User Guide at http://www.oracle.com/technology/tech/xml/xdk/doc/production/plsql/doc/plsql/xsu/xsu_userguide.html).
+
</li>
+
 
+
<li>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).
+
For more information on binary attachments, see Section 12.16, "Optimizing Storage and Retrieval of Binary Data in XML".
+
</li>
+
 
+
This table shows metadata from a typical database, and [[#Example 9–4]] 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
+
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 HIREDATE 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
+
 
+
<span id="Example 9-4"></span>
+
'''''Corresponding eclipselink-dbws-schema.xsd'''''
+
 
+
<source lang="xml">
+
<?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>
+
</source>
+
 
+
For more information, see [[#Creating Deployment Files for EclipseLink Database Web Services]]
+
 
+
 
+
==eclipselink-dbws-builder.xml==
+
The eclipselink-dbws-builder.xml  file is used only with EclipseLink database Web services (see [[Introduction to EclipseLink#Considering EclipseLink Database Web Service Architecture]]). The EclipseLink database Web service command-line tool oracle.toplink.tools.dbws.DBWSBuilder processes the elements described in this file to produce the requisite EclipseLink database Web services files (see [[#eclipselink-dbws.xml File] and Section 9.1.7, "eclipselink-dbws-schema.xsd").
+
 
+
The EclipseLink runtime uses the builder properties (see [[#Table 9–4]) 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]] shows.
+
 
+
 
+
'''''eclipselink-dbws-builder.xml File Elements (DBWSBuilder Properties)'''''
+
+
{| class="RuleFormalWideMax" dir="ltr" title="eclipselink-dbws-builder.xml File Elements (DBWSBuilder Properties)." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t2" align="left" valign="bottom" | '''Element'''
+
! 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" |
+
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:
+
<tt>
+
<servlet-mapping>
+
    ...
+
    <url-pattern>
+
        /servlet/MyWebService
+
    </url-pattern>
+
</servlet-mapping>
+
</tt>
+
|
+
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 oracle.toplink.tools.sessionconfiguration.SessionCustomizer class name to add to the EclipseLink database Web service sessions.xml file.
+
For more information, see Section 13.4, "Using the Session Customizer Class".
+
|
+
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:
+
*off–Disable logging.
+
*severe–Logs exceptions indicating EclipseLink cannot continue, as well as any exceptions generated during login. This includes a stack trace.
+
*warning–Logs exceptions that do not force EclipseLink to stop, including all exceptions not logged with severe level. This does not include a stack trace.
+
*info–Logs the login/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
+
|}
+
 
+
<span id="Example 9-5"></span>
+
'''''eclipselink-dbws-build.xml File'''''
+
 
+
<source lang="xml">
+
<?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>
+
</source>
+
 
+
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 [[#Example 9–5]] uses.
+
This table lists attributes common to all three builder operations.
+
 
+
<span id="Table 9–5"></span>
+
'''''Common Attributes of Builder Operations'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="eclipselink-dbws.xml File Elements." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t2" align="left" valign="bottom" | '''Attribute'''
+
! id="r1c2-t2" align="left" valign="bottom" | '''Description'''
+
! id="r1c2-t2" align="left" valign="bottom" | '''Default'''
+
|- align="left" valign="top"
+
| align="left" |
+
name
+
|
+
Name of the operation.
+
|
+
None
+
|-
+
|
+
isCollection
+
|Specifies whether or not the procedure returns multiple results. The following are valid values:
+
*true - the operation returns more than a single row.
+
*false - the operation returns a single row.
+
|
+
false
+
|-
+
|
+
isSimpleXMLFormat
+
|
+
Specifies whether or not the procedure returns information in the Simple XML Format (SXF). The following are valid values:
+
*true - the operation returns information in the Simple XML Format.
+
*false - the operation returns information in the Simple XML Format.
+
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:
+
*true - the operation returns binary data as a SOAP attachment.
+
*false - the operation does not return binary data as a SOAP attachment.
+
|
+
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.
+
<span id="Table 9–6"></span>
+
 
+
'''''Attributes of the procedure Operation'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="eclipselink-dbws.xml File Elements." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t2" align="left" valign="bottom" | '''Attribute'''
+
! id="r1c2-t2" align="left" valign="bottom" | '''Description'''
+
|- align="left" valign="top"
+
| align="left" |
+
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.
+
<span id="Table 9–7"></span>
+
 
+
'''''Attributes of the table Operation'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="eclipselink-dbws.xml File Elements." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t2" align="left" valign="bottom" | '''Attribute'''
+
! id="r1c2-t2" align="left" valign="bottom" | '''Description'''
+
|- align="left" valign="top"
+
| align="left" |
+
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).
+
|}
+
 
+
 
+
 
+
 
+
 
+
----
+
''[[EclipseLink User's Guide Copyright Statement|Copyright Statement]]''
+
 
+
  
 
[[Category: EclipseLink User's Guide]]
 
[[Category: EclipseLink User's Guide]]
 
[[Category: Release 1.1]]
 
[[Category: Release 1.1]]
 
[[Category: DBWS]]
 
[[Category: DBWS]]

Latest revision as of 07:50, 1 November 2012

For EclipseLink DBWS documentation,including JAX-WS and JAX-RS, see http://www.eclipse.org/eclipselink/dbws.php