Jump to: navigation, search

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

m (EclipseLink DBWSBuilder File)
Line 4: Line 4:
 
The <code>DBWSBuilder</code> design-time utility processes the elements in this file to produce the requisite EclipseLink DBWS service
 
The <code>DBWSBuilder</code> design-time utility processes the elements in this file to produce the requisite EclipseLink DBWS service
 
descriptor and accompanying files. The XML Schema definition for a <code>DBWSBuilder</code> file is
 
descriptor and accompanying files. The XML Schema definition for a <code>DBWSBuilder</code> file is
<tt><b>eclipselink-dbws-builder_1.0.xsd</b></tt> and can be found in the <tt>META-INF/</tt> directory in the
+
<tt>eclipselink-dbws-builder_1.0.xsd</tt> and can be found in the <tt>META-INF/</tt> directory of the
 
<tt>eclipselink-dbwsutils.jar</tt> file, located in the <tt><ECLIPSELINK_HOME>/utils/dbws/</tt> directory.
 
<tt>eclipselink-dbwsutils.jar</tt> file, located in the <tt><ECLIPSELINK_HOME>/utils/dbws/</tt> directory.
The file has two main sections - global properties settings and specific operation settings.
+
The file has two main sections: global properties settings and specific operation settings.
 
<br/>
 
<br/>
 +
 
{| 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"
 
{| 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"
 
|- align="left" valign="top"
Line 64: Line 65:
 
<tt>contextRoot</tt>
 
<tt>contextRoot</tt>
 
|
 
|
The value of the web.xml file servlet-mapping element's url-pattern sub-element:
+
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">
 
<source lang="xml" enclose="div">
 
Example:
 
Example:
Line 82: Line 84:
 
<tt>dataSource</tt>
 
<tt>dataSource</tt>
 
|
 
|
JNDI datasource location for the EclipseLink sessions.xml file
+
JNDI datasource location for the EclipseLink <tt>sessions.xml</tt> file.
You must configure a JNDI datasource before deploying your EclipseLink DBWS to a Java-EE server
+
You must configure a JNDI data source before deploying your EclipseLink DBWS to a Java-EE server.
 
|
 
|
 
No
 
No
Line 92: Line 94:
 
<tt>sessionsFileName</tt>
 
<tt>sessionsFileName</tt>
 
|
 
|
The name of EclipseLink sessions.xml file to add to the EclipseLink DBWS service archive file.
+
The name of EclipseLink <tt>sessions.xml</tt> file to add to the EclipseLink DBWS service archive file.
 
|
 
|
 
No
 
No
Line 109: Line 111:
 
<tt>orSessionCustomizerClassName</tt>
 
<tt>orSessionCustomizerClassName</tt>
 
|
 
|
The name of a Java class that implements the <b><code>eclipselink.persistence.config.SessionCustomizer</code></b> interface.
+
The name of a Java class that implements the <code>eclipselink.persistence.config.SessionCustomizer</code> interface.
The name is added to the EclipseLink sessions.xml file, allowing the ORM project to be customized.
+
The name is added to the EclipseLink <tt>sessions.xml</tt> file, allowing for customization of the object-relational mappings project.
 
|
 
|
 
No
 
No
Line 119: Line 121:
 
<tt>oxSessionCustomizerClassName</tt>
 
<tt>oxSessionCustomizerClassName</tt>
 
|
 
|
The name of a Java class that implements the <b><code>eclipselink.persistence.config.SessionCustomizer</code></b> interface.
+
The name of a Java class that implements the <code>eclipselink.persistence.config.SessionCustomizer</code> interface.
The name is added to the EclipseLink sessions.xml file, allowing the OXM project to be customized.
+
The name is added to the EclipseLink <tt>sessions.xml</tt> file, allowing for customization of the object-XML mappings project.
 
|
 
|
 
No
 
No
Line 129: Line 131:
 
<tt>wsdlLocationURI</tt>
 
<tt>wsdlLocationURI</tt>
 
|
 
|
The URI of this EclipseLink Database Web service's WSDL (used by Web service tools to generate client code).
+
The URI of this EclipseLink Database Web service's WSDL (used by Web service tools to generate the client code).
 
|
 
|
 
No
 
No
Line 138: Line 140:
 
<tt>logLevel</tt>
 
<tt>logLevel</tt>
 
|
 
|
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 <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 java.util.logging.Level values:
+
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:
*<b><tt>off</tt></b> - Disable logging.
+
* <tt>off</tt> - Disable logging.
*<b><tt>severe</tt></b> - Logs exceptions indicating EclipseLink cannot continue, as well as any exceptions generated during login. This includes a stack trace.
+
* <tt>severe</tt> - Logs exceptions indicating EclipseLink cannot continue, as well as any exceptions generated during login. Includes a stack trace.
*<b><tt>warning</tt></b> - Logs exceptions that do not force EclipseLink to stop, including all exceptions not logged with severe level. This does not include 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.
*<b><tt>info</tt></b> - Logs the login/logout per sever session, including the user name. After acquiring the session, detailed information is logged.
+
* <tt>info</tt> - Logs the login and logout per sever session, including the user name. After acquiring the session, detailed information is logged.
*<b><tt>config</tt></b> - Logs only login, JDBC connection, and database information.
+
* <tt>config</tt> - Logs only login, JDBC connection, and database information.
*<b><tt>fine</tt></b> - Logs SQL.
+
* <tt>fine</tt> - Logs SQL.
*<b><tt>finer</tt></b> - Similar to warning. Includes stack trace.
+
* <tt>finer</tt> - Similar to warning. Includes stack trace.
*<b><tt>finest</tt></b> - Includes additional low level information.
+
* <tt>finest</tt> - Includes additional low level information.
 
|
 
|
 
No
 
No
Line 155: Line 157:
 
|
 
|
 
<tt>targetNameSpace</tt>
 
<tt>targetNameSpace</tt>
|The URI of the target namespace that the EclipseLink Database Web service inserts into the '''eclipselink-dbws-schema.xsd''' file.
+
|The URI of the target namespace that the EclipseLink Database Web service inserts into the <tt>eclipselink-dbws-schema.xsd</tt> file.
 
|
 
|
 
No
 
No
Line 161: Line 163:
 
urn: + <tt>projectName</tt>
 
urn: + <tt>projectName</tt>
 
|}
 
|}
 +
 +
 
<br/>
 
<br/>
 
The following tables describe attributes of builder operations.
 
The following tables describe attributes of builder operations.
 
<br/>
 
<br/>
This table lists attributes common to all three builder operations - <b>table</b>, <b>procedure</b> and <b>sql</b>.
+
This table lists attributes common to all three builder operations: <tt>table</tt>, <tt>procedure</tt> and <tt>sql</tt>.
 +
 
 
{| class="RuleFormalWideMax" dir="ltr" title="<b>Common Attributes of Builder Operations</b>" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormalWideMax" dir="ltr" title="<b>Common Attributes of Builder Operations</b>" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
|- align="left" valign="top"
 
|- align="left" valign="top"
Line 182: Line 187:
 
<tt>isCollection</tt>
 
<tt>isCollection</tt>
 
|Specifies whether or not the procedure returns multiple results. The following are valid values:
 
|Specifies whether or not the procedure returns multiple results. The following are valid values:
*true - the operation returns more than a single row.
+
* <tt>true</tt> - the operation returns more than a single row.
*false - the operation returns a single row.
+
* <tt>false</tt> - the operation returns a single row.
 
|
 
|
false
+
<tt>false</tt>
 
|-
 
|-
 
|
 
|
Line 191: Line 196:
 
|
 
|
 
Specifies whether or not the procedure returns information in the Simple XML Format (SXF). The following are valid values:
 
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.
+
* <tt>true</tt> - the operation returns information in the Simple XML Format.
*false - the operation returns information in the Simple XML Format.
+
* <tt>false</tt> - the operation returns information in the Simple XML Format.
 
For more information, see foobar
 
For more information, see foobar
 
|
 
|
false
+
<tt>false</tt>
 
|-
 
|-
 
|
 
|
 
<tt>simpleXMLFormatTag</tt>
 
<tt>simpleXMLFormatTag</tt>
 
|
 
|
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 foobar
+
For more information, see (Information pending).
 
|
 
|
<simple-xml-format>
+
<tt><simple-xml-format></tt>
 
|-
 
|-
 
|
 
|
 
<tt>xmlTag</tt>
 
<tt>xmlTag</tt>
 
|
 
|
The name of the grouping XML element-tag for rows.
+
The name of the grouping XML element tag for rows.
For more information, see foobar
+
For more information, see (Information pending).
 
|
 
|
<simple-xml>
+
<tt><simple-xml></tt>
 
|-
 
|-
 
|
 
|
Line 217: Line 222:
 
|
 
|
 
Specifies whether or not the operation returns binary data as a SOAP attachment. The following are valid values:
 
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.
+
* <tt>true</tt> - the operation returns binary data as a SOAP attachment.
*false - the operation does not return binary data as a SOAP attachment.
+
* <tt>false</tt> - the operation does not return binary data as a SOAP attachment.
 
|
 
|
false
+
<tt>false</tt>
 
|-
 
|-
 
|
 
|
 
<tt>returnType</tt>
 
<tt>returnType</tt>
|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.
+
|Specifies a return type when the operation's return type cannot be deduced from database metadata. Valid values are any type that the <tt>eclipselink-dbws-schema.xsd</tt> file defines.
 
Note: This attribute is optional.
 
Note: This attribute is optional.
 
|
 
|
Line 230: Line 235:
 
|}
 
|}
 
<br/>
 
<br/>
This table lists attributes of the <b>procedure</b> operation.
+
 
 +
 
 +
This table lists attributes of the <tt>procedure</tt> operation:
 
<br/>
 
<br/>
 
{| class="RuleFormalWideMax" dir="ltr" title="Attributes of the <b>procedure</b> Operation" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormalWideMax" dir="ltr" title="Attributes of the <b>procedure</b> Operation" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
Line 254: Line 261:
 
|}
 
|}
  
This table lists attributes of the <b>table</b> operation.
+
This table lists attributes of the <tt>table</tt> operation:
 
{| class="RuleFormalWideMax" dir="ltr" title="Attributes of the <b>table</b> Operation" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormalWideMax" dir="ltr" title="Attributes of the <b>table</b> Operation" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
|- align="left" valign="top"
 
|- align="left" valign="top"
Line 276: Line 283:
 
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).
 
|}
 
|}
 +
  
 
<span id="Example 9-5"></span>
 
<span id="Example 9-5"></span>
 
Example <code>DBWSBuilder</code> builder xml file:
 
Example <code>DBWSBuilder</code> builder xml file:
 +
 
<source lang="xml">
 
<source lang="xml">
 
<?xml version="1.0" encoding="UTF-8"?>
 
<?xml version="1.0" encoding="UTF-8"?>
Line 310: Line 319:
 
</source>
 
</source>
  
===Graphical view of EclipseLink DBWS Service Descriptor's Schema <code>eclipselink-dbws_1.0.xsd</code>===
+
 
 +
===Graphical View of EclipseLink DBWS Service Descriptor Schema eclipselink-dbws_1.0.xsd===
 
[[Image:dbws-builder_1_0.png]]
 
[[Image:dbws-builder_1_0.png]]
  

Revision as of 11:41, 6 April 2009

EclipseLink DBWSBuilder File

The DBWSBuilder design-time utility processes the elements in this file to produce the requisite EclipseLink DBWS service descriptor and accompanying files. The XML Schema definition for a DBWSBuilder file is eclipselink-dbws-builder_1.0.xsd and can be found in the META-INF/ directory of the eclipselink-dbwsutils.jar file, located in the <ECLIPSELINK_HOME>/utils/dbws/ directory. The file has two main sections: global properties settings and specific operation settings.

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



The following tables describe attributes of builder operations.
This table lists attributes common to all three builder operations: table, procedure and sql.

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 foobar

false

simpleXMLFormatTag

The name of the root-level simple XML format element tag. For more information, see (Information pending).

<simple-xml-format>

xmlTag

The name of the grouping XML element tag for rows. For more information, see (Information pending).

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

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


Example DBWSBuilder builder 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>


Graphical View of EclipseLink DBWS Service Descriptor Schema eclipselink-dbws_1.0.xsd

Dbws-builder 1 0.png


Copyright Statement