Oracle® Retail Integration Bus Service-Oriented Architecture Enabler Tool Guide Release 19.0 F22952-01 |
|
Previous |
Next |
The Service Definition Library XML file (ServiceDef) is the mandatory input for creating a Java EE or a PL/SQL service provider. This file should contain all the details about the Web services that need to be created.
This chapter provides a detailed description of each section of the schema as well as instructions for managing the Service Definition Library XML file.
This section discusses the elements of the schema, beginning with the root element and including child elements.
This is the root element of the schema. The following is an example of the serviceProviderDefLibrary element:
<xs:element name="serviceProviderDefLibrary"> <xs:complexType> <xs:sequence> <xs:element ref="service" maxOccurs="unbounded" /> </xs:sequence> <xs:attribute name="appName" type="xs:string" use="required"/> <xs:attribute name="version" type="xs:string" use="optional" default="v1"/> <xs:attribute name="serviceNamespacePattern" type="xs:string" use="optional" default="http://www.oracle.com/retail/APPNAME/integration/services/SERVICENAMEService/VERSION"/> </xs:complexType> </xs:element>
The serviceProviderDefLibrary has the following attributes:
appName
This is the name of the application for which the .ear file is being built. When the .ear file is generated, the name of the .ear file starts with the application name. The format of the generated .ear file is <appName>-service.ear. For example, if the appName is rms, the .ear file name is rms-service.ear.
serviceNamespacePattern
This attribute specifies the pattern for the namespaces that are generated for the Web services. The default value for this attribute is http://www.oracle.com/retail/APPNAME/integration/services/SERVICENAMEService/VERSION.
Version
This is the version of the service definition.
The serviceProviderDefLibrary contains the following elements:
Each service element in serviceProviderDefLibrary represents one Web service. The service provider definition should have at least one service defined in it.
The following is an example of the service element:
<xs:element name="service"> <xs:complexType> <xs:sequence> <xs:element ref="documentation" minOccurs="0" /> <xs:element ref="operation" maxOccurs="unbounded" /> </xs:sequence> <xs:attribute name="name" type="xs:string" use="required"/> <xs:attribute name="serviceNamespace" type="xs:string" use="optional"/> <xs:attribute name="serviceVersion" type="xs:string" use="optional" default="v1"/> <xs:attribute name="custom" type="xs:boolean" use="optional" default="false"/> </xs:complexType> </xs:element>
The service element has the following attributes:
name
This is the name of the Web service to be created.
serviceNamespace
This is the namespace in which the Web service will be created.
serviceVersion
This is the version of the Web service. The default value is v1.
The service element contains the following elements:
Documentation
This field describes the purpose of the service.
Operation
The operation represents the method in the generated Web service. Each service should contain at least one operation.
The following is an example of the operation element:
<xs:element name="operation"> <xs:complexType> <xs:sequence> <xs:element ref="documentation" minOccurs="0" /> <xs:element ref="input" /> <xs:element ref="output" minOccurs="0" /> <xs:element ref="fault" minOccurs="0" maxOccurs="unbounded" /> </xs:sequence> <xs:attribute name="name" type="xs:string" use="required"/> <xs:attribute name="suffix" default="inputType"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="inputType" /> <xs:enumeration value="outputType" /> <xs:enumeration value="NONE" /> </xs:restriction> </xs:simpleType> </xs:attribute> <xs:attribute name="custom" type="xs:boolean" use="optional" default="false"/> </xs:complexType> </xs:element>
The operation element has the following attributes:
name
This is the name of the operation.
suffix
This is the string to be added to the end of the operation name. One of the following values is supported for this attribute:
inputType
If the suffix value is inputType, the input type name of the operation is added to the generated method name. For example, if the operation name is create and input type for that operation name is SupplierDesc, the generated operation name will be createSupplierDesc.
outputType
If the suffix value is outputType, the output type name of the operation is added to the generated method name. For example, if the operation name is create and output type for that operation name is SupplierRef, the generated operation name will be createSupplierRef.
NONE
If the suffix value is NONE, a suffix is not added to the operation name.
Note: If no value is provided for the suffix attribute, inputType is used as the default value. |
The operation element contains the following child elements:
Documentation
Input
Output
Fault
Fault contains the following elements:
Documentation
The description of the fault.
Faulttype
The name of the fault.
The Service Definition Library XML file is the single source of truth for the RSE tool. This section discusses the creation and management of the file.
The Service Definition Library XML example in "Appendix: Sample ServiceProviderDefLibrary.xml" can be used as the initial template. Use the instructions in the Service Definition Library XML File section to construct the ServiceDef according to the goals of the service requirements.
As discussed in the Concepts section, the creation of this file is the result of the analysis phase and part of the Service Design phase. The template provides the placeholders for the standard service components: service name, operation name, and the contracts for each of the operations, as well as the standard faults.
The ServiceDef should be created and managed (or governed) as a service-oriented architecture asset in a source code control system. It is as important as the Service Contracts (XSDS) and implementation source code.
To change the version of the service definition library file, a version attribute must be added to the root element, serviceProviderDefLibrary.
For example:
<serviceProviderDefLibrary appName="rms" xmlns=http://www.oracle.com/retail/integration/services/serviceProviderDefLibrary/v1 version="v2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> ... </serviceProviderDefLibrary>
To change the application name in the services, edit the appName attribute in the root element, serviceProviderDefLibrary.
For example:
<serviceProviderDefLibrary appName="editThisAppName" xmlns=http://www.oracle.com/retail/integration/services/serviceProviderDefLibrary/v1 version="v2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> ... </serviceProviderDefLibrary>
To rename a service, edit the name attribute in the service element.
For example:
<serviceProviderDefLibrary appName="rms" xmlns=http://www.oracle.com/retail/integration/services/serviceProviderDefLibrary/v1 version="v2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <service name="EditThisName"> ... </serviceProviderDefLibrary>
To rename an operation in the service, edit the name attribute of the operation element.
To add a new service to library, add a new service element with its child elements.
For example:
<serviceProviderDefLibrary appName="rmscostchange" xmlns=http://www.oracle.com/retail/integration/services/serviceProviderDefLibrary/v1 version="v2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <service name="ExistingService"> <operation name="existingOperation"> <documentation></documentation> <input type="XXX"> <documentation></documentation> </input> <output type="YYY"> <documentation></documentation> </output> <fault faultType="IllegalArgumentWSFaultException"> <documentation>Throw this exception when a "soap:Client" side message problem occurs.</documentation> </fault> <fault faultType="EntityAlreadyExistsWSFaultException"> <documentation>Throw this exception when the attempt made to create a object that already exists.</documentation> </fault> <fault faultType="IllegalStateWSFaultException"> <documentation>Throw this exception when an unknown "soap:Server" side problem ccurs.</documentation> </fault> </operation> </service> <service name="AddedNewServiceName"> <operation name="Operation"> <documentation></documentation> <input type="XXX"> <documentation></documentation> </input> <output type="YYY"> <documentation></documentation> </output> <fault faultType="IllegalArgumentWSFaultException"> <documentation>Throw this exception when a soap:Client" side message problem occurs.</documentation> </fault> <fault faultType="EntityAlreadyExistsWSFaultException"> <documentation>Throw this exception when the attempt made to create a object that already exists.</documentation> </fault> <fault faultType="IllegalStateWSFaultException"> <documentation>Throw this exception when an unknown "soap:Server" side problem occurs.</documentation> </fault> </operation> </service> ... </serviceProviderDefLibrary>
To add a new operation to a service, add the operation element with its child elements.
For example:
<service name="service"> <service name="ServiceName"> <operation name="NewAddedOperation"> <documentation></documentation> <input type="XXX"> <documentation></documentation> </input> <output type="YYY"> <documentation></documentation> </output> <fault faultType="IllegalArgumentWSFaultException"> <documentation>Throw this exception when a "soap:Client" side message problem occurs.</documentation> </fault> <fault faultType="EntityAlreadyExistsWSFaultException"> <documentation>Throw this exception when the attempt made to create a object that already exists.</documentation> </fault> <fault faultType="IllegalStateWSFaultException"> <documentation>Throw this exception when an unknown "soap:Server" side problem ccurs.</documentation> </fault> </operation> <operation name="ExistingOperation"> <documentation></documentation> <input type="XXX"> <documentation></documentation> </input> <output type="YYY"> <documentation></documentation> </output> <fault faultType="IllegalArgumentWSFaultException"> <documentation>Throw this exception when a soap:Client" side message problem occurs.</documentation> </fault> <fault faultType="EntityAlreadyExistsWSFaultException"> <documentation>Throw this exception when the attempt made to create a object that already exists.</documentation> </fault> <fault faultType="IllegalStateWSFaultException"> <documentation>Throw this exception when an unknown "soap:Server" side problem occurs.</documentation> </fault> </operation> </service>
To delete a service from the library, remove the service element and all its child elements from the library.
To delete an operation from the service, delete the operation element and all its child elements.
Users can define a new exception in the service definition library. The RSE tool creates the artifacts with this new exception.
For example:
<operation name="ExistingOperation"> <documentation></documentation> <input type="XXX"> <documentation></documentation> </input> <output type="YYY"> <documentation></documentation> </output> <fault faultType="IllegalArgumentWSFaultException"> <documentation>Throw this exception when a "soap:Client" side message problem occurs.</documentation> </fault> <fault faultType="EntityAlreadyExistsWSFaultException"> <documentation>Throw this exception when the attempt made to create a object that already exists.</documentation> </fault> <fault faultType="IllegalStateWSFaultException"> <documentation>Throw this exception when an unknown "soap:Server" side problem occurs.</documentation> </fault> <fault faultType="UserDefinedException"> <documentation>This is user defined exception for a particular scenerio.</documentation> </fault> </operation>