Jump to: navigation, search

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

m (eclipselink-dbws-builder.xml)
m (What You May Need to Know About Builder Operations)
Line 384: Line 384:
 
|
 
|
 
false
 
false
|
 
 
|-
 
|-
 +
|
 
simpleXMLFormatTag
 
simpleXMLFormatTag
|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 [[#Unstructured Data]].
 
For more information, see [[#Unstructured Data]].
 
|
 
|
 
<simple-xml-format>
 
<simple-xml-format>
|
 
 
|-
 
|-
 +
|
 
xmlTag
 
xmlTag
|The name of the grouping XML element-tag for rows.
+
|
 +
The name of the grouping XML element-tag for rows.
 
For more information, see [[#Unstructured Data]].
 
For more information, see [[#Unstructured Data]].
 
|
 
|
Line 468: Line 470:
 
|
 
|
 
A pattern that matches one or more table names in the database identified by the parent operation (supports SQL-92 % wild-card).
 
A pattern that matches one or more table names in the database identified by the parent operation (supports SQL-92 % wild-card).
|}
 
 
This table lists attributes of the sql operation.
 
<span id="Table 9–8"></span>
 
 
'''''Attributes of the sql 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" |
 
text
 
|
 
The name of the SQL operation. The parent operation specifies the database on which to perform the SQL operation.
 
|}
 
 
The sql operation can have a binding nested element that binds type information to JDBC argument markers in the SQL text. For more information, see Section 9.8.5, "Binding".
 
The table operation can have nested sql or procedure operations associated with it. These operations can use the table's schema to return entities.
 
 
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
 
| align="left" |
 
'''Note''': Typically, sql and procedure operations return simpleXMLFormat rows.
 
 
|}
 
|}
  

Revision as of 14:45, 11 March 2009

eclipselink-dbws.xml File

The eclipselink-dbws.xml file is used only with EclipseLink database Web services (see #Introdution to EclipseLink (ELUG)#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

Element Description Required Default

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

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

  1. 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).
  2. 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".
  3. 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
    

    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


    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)

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

    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 #Example 9–5 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:
    • 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.

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




    Copyright Statement