|
|
| (2 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| − | <b>Note: A basic overview of EclipseLink Database Web Services (DBWS) can be found</b> [[EclipseLink/FAQ/WhatIsDBWS|here]]
| + | [[Image:Elug draft icon.png]] '''For the latest EclipseLink documentation, please see http://www.eclipse.org/eclipselink/documentation/ ''' |
| − | __TOC__
| + | |
| | | | |
| | + | For the latest EclipseLink DBWS documentation, see |
| | + | '''[http://www.eclipse.org/eclipselink/documentation/2.4/dbws/toc.htm Developing Persistence Architectures Using EclipseLink Database Web Services, Release 2.4]''' |
| | | | |
| − | ==Creating EclipseLink DBWS Services==
| |
| − | You can generate a WAR file containing the EclipseLink DBWS service descriptor along with all required deployment artifacts for a JAX-WS 2.0 Web service (WSDL, XML schema, <tt>web.xml</tt>, EclipseLink object-relational mapping (ORM) and object-XML mapping (OXM) native project XML files, and so on).
| |
| | | | |
| − | <onlyinclude>
| + | <b>Note: A basic overview of EclipseLink Database Web Services (DBWS) can be found</b> [[EclipseLink/FAQ/WhatIsDBWS|here]] |
| − | <source lang="text" enclose="div">
| + | |
| − | root of war file
| + | |
| − | \---web-inf
| + | |
| − | |
| + | |
| − | | web.xml
| + | |
| − | |
| + | |
| − | +---classes
| + | |
| − | | +---foo -- optional domain classes (typically not required)
| + | |
| − | | | \---bar
| + | |
| − | | | Address.class
| + | |
| − | | | Employee.class
| + | |
| − | | | PhoneNumber.class
| + | |
| − | | |
| + | |
| − | | +---META-INF
| + | |
| − | | | eclipselink-dbws.xml
| + | |
| − | | | eclipselink-dbws-or.xml
| + | |
| − | | | eclipselink-dbws-ox.xml
| + | |
| − | | | eclipselink-dbws-sessions.xml -- name can be overridden by <sessions-file> entry in eclipselink-dbws.xml
| + | |
| − | | |
| + | |
| − | | \---_dbws
| + | |
| − | | DBWSProvider.class -- auto-generated JAX-WS 2.0 Provider
| + | |
| − | |
| + | |
| − | \---wsdl
| + | |
| − | eclipselink-dbws-schema.xsd
| + | |
| − | eclipselink-dbws.wsdl
| + | |
| − | swaref.xsd
| + | |
| − | </source>
| + | |
| − | | + | |
| − | | + | |
| − | {| class="RuleFormalWideMax" dir="ltr" title="<b>EclipseLink DBWS Service <code>.war</code> File Contents</b>" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
| + | |
| − | |+ <b>EclipseLink DBWS Service <code>.war</code> File Contents</b>
| + | |
| − | |- align="left" valign="top"
| + | |
| − | ! id="r1c1-t2" align="left" valign="bottom" | '''File'''
| + | |
| − | ! id="r1c2-t2" align="left" valign="bottom" | '''Description'''
| + | |
| − | |- align="left" valign="top"
| + | |
| − | | align="left" |
| + | |
| − | |-
| + | |
| − | |<tt>web.xml</tt>
| + | |
| − | |The Web application deployment file <br />(required for deployment as a JAX-WS Web service - see [http://jcp.org/en/jsr/detail?id=109 JSR-109] for more details).
| + | |
| − | |-
| + | |
| − | |<tt>eclipselink-dbws.xml</tt>
| + | |
| − | |[[EclipseLink/UserGuide/DBWS/Overview/EclipseLink_DBWS_Service_Descriptor_File_(ELUG)|The EclipseLink DBWS service descriptor file]]<br/>(described in full in the EclipseLink User Guide).
| + | |
| − | |-
| + | |
| − | |<tt>eclipselink-dbws-or.xml</tt>
| + | |
| − | |The EclipseLink ORM project XML file.<br/>For more information, see [[Introduction to Relational Projects (ELUG)]].
| + | |
| − | |-
| + | |
| − | |<tt>eclipselink-dbws-ox.xml</tt>
| + | |
| − | |The EclipseLink OXM project XML file.<br/>For more information, see [[Introduction to XML Projects (ELUG)]].
| + | |
| − | |-
| + | |
| − | |<tt>eclipselink-dbws-sessions.xml</tt>
| + | |
| − | |The EclipseLink sessions.xml file for the EclipseLink DBWS service.<br/>It contains references to the EclipseLink ORM and OXM project XML files.<br/>For more information, see [[Introduction to EclipseLink Sessions (ELUG)]].
| + | |
| − | |-
| + | |
| − | |<tt>eclipselink-dbws-schema.xsd</tt>
| + | |
| − | |Contains XML type definitions for operation arguments and return types.<br/>The <tt>DBWSBuilder</tt> utility automatically generates this file from database<br/>metadata to derive element-tag names and types.
| + | |
| − | |-
| + | |
| − | |<tt>eclipselink-dbws.wsdl</tt>
| + | |
| − | |Contains entries for all operations in the EclipseLink DBWS service.<br />(required for deployment as a JAX-WS Web service - see [http://jcp.org/en/jsr/detail?id=109 JSR-109] for more details).
| + | |
| − | |-
| + | |
| − | |<tt>swaref.xsd</tt>
| + | |
| − | |(optional) Contains XML type definitions for SOAP attachments.
| + | |
| − | |-
| + | |
| − | |}
| + | |
| − | | + | |
| − | | + | |
| − | Note that the files <tt>swaref.xsd</tt> and <tt>web.xml</tt> have names and content determined by their roles in Web deployment and cannot be changed.
| + | |
| − | </onlyinclude>
| + | |
| − | The deployable <tt>.war</tt> file has been verified to work with the [http://www.oracle.com/technology/software/products/ias/htdocs/wls_main.html?rssid=rss_otn_soft Oracle WebLogic Server 10.3 JavaEE container].
| + | |
| − | | + | |
| − | An alternate deployable JAR file has been verified to work as a JavaSE 6 'container-less' [http://java.sun.com/javase/6/docs/api/javax/xml/ws/Endpoint.html EndPoint] (see <br /> the example <i>[[EclipseLink/Examples/DBWS/AdvancedJavase6Containerless|EclipseLink DBWS Service deployed as a JavaSE 6 'containerless' EndPoint]]</i> for details).
| + | |
| − | | + | |
| − | | + | |
| − | | + | |
| − | This section describes [[#How to Create EclipseLink DBWS Services Using the DBWSBuilder Utility|how to create EclipseLink DBWS services using the <tt>DBWSBuilder</tt> utility]].
| + | |
| − | ===How to Create EclipseLink DBWS Services Using the DBWSBuilder Utility===
| + | |
| − | You can use the EclipseLink DBWS design-time utility <tt>DBWSBuilder</tt> to create deployment files. <tt>DBWSBuilder</tt> is a Java application that processes the operations described in an [[EclipseLink dbws-builder.xml File (ELUG)#eclipselink-dbws-builder.xml|EclipseLink DBWS builder XML file]] to produce all the required deployment artifacts.
| + | |
| − | | + | |
| − | Be sure to set the following environment variables in the <tt><ECLIPSELINK_HOME>\utils\dbws\setenv.cmd</tt> (or <tt>setenv.sh</tt> file) before invoking <tt>DBWSBuilder</tt>:
| + | |
| − | * <tt>JAVA_HOME</tt>
| + | |
| − | * <tt>DRIVER_CLASSPATH</tt>
| + | |
| − | | + | |
| − | There are script files provided for invoking <tt>DBWSBuilder</tt>. They are located in the <tt><ECLIPSELINK_HOME>\utils\dbws</tt> directory. The scripts are <tt>dbwsbuilder.cmd</tt> for Windows usage, and <tt>dbwsbuilder.sh</tt> for other operating systems.
| + | |
| − | | + | |
| − | <source lang="text">
| + | |
| − | DBWSBuilder usage - [] indicates optional argument:
| + | |
| − | prompt > dbwsbuilder.cmd -builderFile {path_to_builder.xml} -stageDir {path_to_stageDir} -packageAs[:archive_flag] {packager} [additional args]
| + | |
| − | Available packagers:
| + | |
| − | -packageAs:[default=archive] javase [jarFilename]
| + | |
| − | -packageAs:[default=archive] wls [warFilename]
| + | |
| − | </source>
| + | |
| − | | + | |
| − | Using <tt>DBWSBuilder</tt>, you can generate an EclipseLink DBWS service from the following sources:
| + | |
| − | * [[#Creating an EclipseLink DBWS Service from a Database Table|an existing relational database table]];
| + | |
| − | * [[#Creating an EclipseLink DBWS Service from a SQL Statement|one or more SQL <tt>SELECT</tt> statements]];
| + | |
| − | * [[#Creating an EclipseLink DBWS Service from a Stored Procedure|a stored procedure]].
| + | |
| − | | + | |
| − | | + | |
| − | ====Creating an EclipseLink DBWS Service from a Database Table====
| + | |
| − | You can create an EclipseLink DBWS builder XML file with a <tt><table></tt> query operation, as follows:
| + | |
| − | | + | |
| − | <source lang="xml" enclose="div">
| + | |
| − | <?xml version="1.0" encoding="UTF-8"?>
| + | |
| − | <dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema">
| + | |
| − | <properties>
| + | |
| − | <property name="projectName">table_test</property>
| + | |
| − | ... database properties ...
| + | |
| − | </properties>
| + | |
| − | <table
| + | |
| − | schemaPattern="%"
| + | |
| − | tableNamePattern="dbws_crud"
| + | |
| − | />
| + | |
| − | </dbws-builder>
| + | |
| − | </source>
| + | |
| − | | + | |
| − | For more information, see the basic example [[EclipseLink/Examples/DBWS/DBWSBasicTable| Creating EclipseLink DBWS Service Based on Database Table]].
| + | |
| − | | + | |
| − | | + | |
| − | ====Creating an EclipseLink DBWS Service from a SQL Statement====
| + | |
| − | You can create an EclipseLink DBWS builder XML file with a <tt><sql></tt> query operation, as follows:
| + | |
| − | | + | |
| − | <source lang="xml" enclose="div">
| + | |
| − | <?xml version="1.0" encoding="UTF-8"?>
| + | |
| − | <dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema"
| + | |
| − | <properties>
| + | |
| − | <property name="projectName">sql_test</property>
| + | |
| − | ... database properties ...
| + | |
| − | </properties>
| + | |
| − | <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>
| + | |
| − | | + | |
| − | =====Parameter Binding=====
| + | |
| − | The SQL <tt>SELECT</tt> statement for a <tt><sql></tt> operation may have parameters that must be bound to a datatype from the <tt>eclipselink-dbws-schema.xsd</tt>, or to any of the basic XSD datatypes. The SQL <tt>SELECT</tt> string uses JDBC-style '?' markers to indicate the position of the argument. The <tt><sql></tt> operation uses nested <tt><binding></tt> elements to match the datatype to the parameters. The order in which <tt><binding></tt> elements are defined must match the order of '?' markers in the SQL string:
| + | |
| − | | + | |
| − | <source lang="xml" enclose="div">
| + | |
| − | <?xml version="1.0" encoding="UTF-8"?>
| + | |
| − | <dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema"
| + | |
| − | <properties>
| + | |
| − | <property name="projectName">sql_binding_test</property>
| + | |
| − | ... database properties ...
| + | |
| − | </properties>
| + | |
| − | <sql name="findEmpByName" isCollection="true" isSimpleXMLFormat="true">
| + | |
| − | <text>
| + | |
| − | <![CDATA[select * from EMP where EMPNO = ? and LAST_NAME = ?]]>
| + | |
| − | </text>
| + | |
| − | <binding name="EMPNO" type="xsd:int"/>
| + | |
| − | <binding name="LAST_NAME" type="xsd:string"/>
| + | |
| − | </sql>
| + | |
| − | </dbws-builder>
| + | |
| − | </source>
| + | |
| − | | + | |
| − | The argument named <tt>"EMPNO"</tt> is bound to an integer type, while the argument named <tt>"LAST_NAME"</tt> is bound to a string type.
| + | |
| − | <br />
| + | |
| − | For more information, see the basic example [[EclipseLink/Examples/DBWS/DBWSBasicSQL|Creating EclipseLink DBWS Service Based on Results Sets from Custom SQL <code>SELECT</code> Statements]].
| + | |
| − | | + | |
| − | ====Creating an EclipseLink DBWS Service from a Stored Procedure====
| + | |
| − | You can create an EclipseLink DBWS builder XML File with a <tt><procedure></tt> query operation, as follows:
| + | |
| − | | + | |
| − | <source lang="xml" enclose="div">
| + | |
| − | <?xml version="1.0" encoding="UTF-8"?>
| + | |
| − | <dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema"
| + | |
| − | <properties>
| + | |
| − | <property name="projectName">procedure_test</property>
| + | |
| − | ... database properties ...
| + | |
| − | </properties>
| + | |
| − | <procedure
| + | |
| − | returnType="empType"
| + | |
| − | catalogPattern="SOME_PKG"
| + | |
| − | schemaPattern="SCOTT"
| + | |
| − | procedurePattern="GetEmployeeByEMPNO_DEPTNO"/>
| + | |
| − | </procedure>
| + | |
| − | </dbws-builder>
| + | |
| − | </source>
| + | |
| − | | + | |
| − | For more information, see the basic example [[EclipseLink/Examples/DBWS/DBWSBasicStoredProcedure|Creating EclipseLink DBWS Service Based on Stored Procedure]].
| + | |
| − | | + | |
| − | ==Customizing an EclipseLink DBWS Service==
| + | |
| − | There are a number use-cases that require an EclipseLink DBWS Service to be customized. The use-cases can be subdivided into the following categories:
| + | |
| − | * [[#How to Perform Simple Customization|simple]] - changing an <element-tag> to an "attribute";
| + | |
| − | * [[#How to Perform Intermediate Customization|intermediate ]] - customizing the EclipseLink ORM or OXM Projects;
| + | |
| − | * [[#How to Perform Advanced Customization|advanced]] - manually generating all required deployment artifacts.
| + | |
| − | | + | |
| − | | + | |
| − | ===How to Perform Simple Customization===
| + | |
| − | See the example [[EclipseLink/Examples/DBWS/DBWSIntermediateAttribute|Changing an <element-tag> to an "attribute"]].
| + | |
| − | | + | |
| − | | + | |
| − | ===How to Perform Intermediate Customization===
| + | |
| − | The primary reason to use an EclipseLink <tt>SessionCustomizer</tt> is to enable programmatic access to the EclipseLink API. Using this API, you can retrieve the object-relational or object-XML mapping descriptors from the session, and then use these descriptors to add, change, or delete mappings. You could also consider turning off the session cache, or changing the transaction isolation level of the database connection.
| + | |
| − | | + | |
| − | The following example shows how to implement a <code>org.eclipse.persistence.config.SessionCustomizer</code>:
| + | |
| − | | + | |
| − | <source lang="java5" enclose="div">
| + | |
| − | package some.java.package;
| + | |
| − | | + | |
| − | import org.eclipse.persistence.config.SessionCustomizer;
| + | |
| − | import org.eclipse.persistence.sessions.Session;
| + | |
| − | import org.eclipse.persistence.sessions.DatabaseLogin;
| + | |
| − | | + | |
| − | public class MySessionCustomizer implements SessionCustomizer {
| + | |
| − | | + | |
| − | public MySessionCustomizer() {
| + | |
| − | }
| + | |
| − | | + | |
| − | public void customize(Sesssion session) {
| + | |
| − | DatabaseLogin login = (DatabaseLogin)session.getDatasourceLogin();
| + | |
| − | login.setTransactionIsolation(DatabaseLogin.TRANSACTION_READ_UNCOMMITTED);
| + | |
| − | }
| + | |
| − | }
| + | |
| − | </source>
| + | |
| − | | + | |
| − | | + | |
| − | In the <tt>DBWSBuilder</tt> builder XML file, specify if the customization applies to the ORM project or the OXM project, as the following example shows:
| + | |
| − | | + | |
| − | <source lang="xml" enclose="div">
| + | |
| − | <?xml version="1.0" encoding="UTF-8"?>
| + | |
| − | <dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema"
| + | |
| − | <properties>
| + | |
| − | <property name="projectName">customize_test</property>
| + | |
| − | ...
| + | |
| − | <property name="orSessionCustomizerClassName">some.java.package.MyORSessionCustomizer</property>
| + | |
| − | </source>
| + | |
| − | | + | |
| − | | + | |
| − | or
| + | |
| − | | + | |
| − | | + | |
| − | <source lang="xml" enclose="div">
| + | |
| − | <?xml version="1.0" encoding="UTF-8"?>
| + | |
| − | <dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema"
| + | |
| − | <properties>
| + | |
| − | <property name="projectName">customize_test</property>
| + | |
| − | ...
| + | |
| − | <property name="oxSessionCustomizerClassName">some.java.package.MyOXSessionCustomizer</property>
| + | |
| − | </source>
| + | |
| − | | + | |
| − | | + | |
| − | For details, see [[Introduction to EclipseLink Sessions (ELUG)#Session_Customization|Session Customization]].
| + | |
| − | | + | |
| − | ===How to Perform Advanced Customization===
| + | |
| − | You can customize an EclipseLink DBWS service by creating your own <tt>project.xml</tt> and <tt>sessions.xml</tt> files.
| + | |
| − | Using your preferred utility, you can do the following:
| + | |
| − | * map your objects to your relational database in an EclipseLink relational project;
| + | |
| − | * map your objects to your XML schema in an EclipseLink XML project:
| + | |
| − | * create an EclipseLink <tt>sessions.xml</tt> file that references both projects.
| + | |
| − | | + | |
| − | In this way, you can control all aspects of the relational and XML mapping. This approach is best when you want to customize most or all details. See the advanced example [[EclipseLink/Examples/DBWS/ExistingMappingFiles|Creating EclipseLink DBWS Service based upon existing ORM and OXM Projects]].
| + | |
| − | | + | |
| − | | + | |
| − | | + | |
| − | ==Using DBWSBuilder API==
| + | |
| − | The EclipseLink DBWS design-time utility, <tt>DBWSBuilder</tt>, is a Java application that generates EclipseLink DBWS files and assembles them into deployable archives. YOu can also set the <tt>DBWSBuilder</tt>’s properties, add table or procedure definitions and SQL operations programmatically through <tt>DBWSBuilder</tt>’s API.
| + | |
| − | | + | |
| − | Information pending
| + | |
| − | | + | |
| − | ----
| + | |
| − | ''[[EclipseLink User's Guide Copyright Statement|Copyright Statement]]''
| + | |
| − | | + | |
| − | | + | |
| − | [[Category: EclipseLink User's Guide]]
| + | |
| − | [[Category: Release 1.1]]
| + | |
| − | [[Category: DBWS]]
| + | |
For the latest EclipseLink documentation, please see http://www.eclipse.org/eclipselink/documentation/