| Oracle® Retail Integration Bus Service-Oriented Architecture Enabler Tool Guide Release 16.0.21 E86940-02 |
|
 Previous |
 Next |
| Oracle® Retail Integration Bus Service-Oriented Architecture Enabler Tool Guide Release 16.0.21 E86940-02 |
|
Previous |
Next |
The REST Service Definition Library XML file (ServiceDef) is the mandatory input for creating a RESTful 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.
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.oracle.com/retail/integration/services/serviceProviderDefLibrary/v1"
xmlns="http://www.oracle.com/retail/integration/services/serviceProviderDefLibrary/v1"
elementFormDefault="qualified">
<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>
<xs:element name="documentation" type="xs:string" />
<xs:element name="header">
<xs:complexType>
<xs:attribute name="type" type="xs:string" use="required"/>
<xs:attribute name="headerName" type="xs:string" use="required"/>
<xs:attribute name="headerRequired" type="xs:boolean" use="optional" default="false"/>
</xs:complexType>
</xs:element>
<xs:element name="input">
<xs:complexType>
<xs:sequence>
<xs:element ref="documentation" minOccurs="0" />
<xs:element ref="header" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
<xs:attribute name="type" type="xs:string" use="required"/>
<xs:attribute name="version" type="xs:string" use="optional" default="v1"/>
<xs:attribute name="custom" type="xs:boolean" use="optional" default="false"/>
<xs:attribute name="identifierNameList" type="xs:string" use="optional" />
</xs:complexType>
</xs:element>
<xs:element name="output">
<xs:complexType>
<xs:sequence>
<xs:element ref="documentation" minOccurs="0" />
<xs:element ref="relations" minOccurs="0"/>
</xs:sequence>
<xs:attribute name="type" type="xs:string" use="required"/>
<xs:attribute name="version" type="xs:string" use="optional" default="v1"/>
<xs:attribute name="custom" type="xs:boolean" use="optional" default="false"/>
</xs:complexType>
</xs:element>
<xs:element name="relations">
<xs:complexType>
<xs:sequence>
<xs:element ref="relatedTo" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="relatedTo">
<xs:complexType>
<xs:attribute name="name" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:pattern value="[a-zA-Z0-9]*|EXTERNAL_SYSTEM"></xs:pattern>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="value" type="xs:string" use="optional" />
</xs:complexType>
</xs:element>
<xs:element name="fault">
<xs:complexType>
<xs:sequence>
<xs:element ref="documentation" minOccurs="0" />
</xs:sequence>
<xs:attribute name="faultType" type="xs:string" use="required"/>
</xs:complexType>
</xs: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:attribute name="operationType" default="READ_WITH_IDENTITY">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="CREATE" />
<xs:enumeration value="READ_WITH_IDENTITY" />
<xs:enumeration value="READ_WITH_PREDICATE" />
<xs:enumeration value="UPDATE" />
<xs:enumeration value="DELETE" />
<xs:enumeration value="PROCESS" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs: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>
</xs:schema>
This is the root element of the schema. The following is an example of the serviceProviderDefLibrary element.
Sample Rest Service Definition Library file:
<serviceProviderDefLibrary appName="rms" xmlns="http://www.oracle.com/retail/integration/services/serviceProviderDefLibrary/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<service name="Suppliers">
<operation name="find" operationType="READ_WITH_PREDICATE" suffix="outputType">
<input type="SupplierColRef" identifierNameList="country_id"/>
<output type="SupplierColDesc">
</output>
<fault faultType="IllegalArgumentWSFaultException" />
</operation>
<operation name="delete" operationType="DELETE">
<input type="SupplierColRef" identifierNameList="country_id"/>
<output type="SupplierColRef">
</output>
<fault faultType="IllegalArgumentWSFaultException" />
</operation>
</service>
</serviceProviderDefLibrary>
There must be a valid appName specified in service def. It must follow these rules:
Must not be empty.
Must be alphanumeric.
Must not start with a number.
There must be at least one service in the service def.
The service name must be unique in the service def.
The service name must follow these rules:
Must not be empty.
Must be alphanumeric.
Must not start with a number.
There must be at least one operation in the service.
For each operation a valid OperationType must be defined. Operation type can be one of the following:
READ_WITH_IDENTITY
READ_WITH_PREDICATE
NAVIGATE_TO_CHILD
CREATE
DELETE
UPDATE
PROCESS
READ_WITH_IDENTITY: To get a unique resource instance. It maps to HTTP GET operation. It requires path parameters which are the attributes to uniquely identify an instance of the resource. For example, SupplierId element of SupplierDesc payload can be an identifier for Supplier service/resource. The request does not contain any body with this method, so "Nothing" is a valid input type for this operation. The values of path parameters are passed to service provider in ServiceOpContext object.
READ_WITH_PREDICATE: To get a resource based on query parameter. Generally it should be used to get collection types of payloads. The request does not contain any body for this operation, so "Nothing" can be used as input type for this operation. The values of request parameter are passed to service provider in ServiceOpContext object.
NAVIGATE_TO_CHILD: To get child element of a resource. The child element must be a top-level element.
CREATE: To create a new instance of the resource that this service represents. It maps to HTTP POST method. The request body contains the object that needs to be created.
DELETE: To delete an existing resource instance. DELETE maps to HTTP DELETE method. The path parameter contains the identifiers to identify a resource instance to be updated. It doesn't have a request body payload.
UPDATE: To update an already existing resource. UPDATE maps to HTTP PUT method. The path parameter contains the identifiers to identify a resource instance to be updated. And the request body contains the full payload to be updated.
PROCESS: To perform any business operation on the existing resource. PROCESS maps to HTTP POST method. And the request body contains the full payload for the operation to be performed.
The operation name must follow these rules:
Must not be empty.
Must be alphanumeric.
Must not start with a number.
Each operation must have a valid input type and output type defined. These types must be the names of valid payload objects.
READ_WITH_PREDICATE operation type is only supported for CREATE and PROCESS operations. DELETE and UPDATE operations are not supported on a collection of objects.
The input type of an operation must have a valid value for the field identifierNameList, which means that the value specified for that field must follow these rules:
It can have comma-separated names of fields.
The fields must be valid elements present in the XSD of the payload name specified in inputType of that operation.
If the service has an operation of type READ_WITH_PREDICATE, then the payload specified in inputType must have an element named "collection_size".That signifies that this service is for collection of objects.
The identifierNameList specified in READ_WITH_IDENTITY is used for building URI for the service. For example, if the service name is "Supplier" and identifierNameList for READ_WITH_IDENTITY operation has a value such as "supplier_id, sup_xref_key" then the URI of that service will be http://<host>:<port>/<contextPath>/SupplierResource/<supplierId>/<sup_xref_key>An example of a request is: http://localhost:7001/rms-service/1/xref1.In this example, "1" will be substituted as the value for supplierId and "xref1" will be substituted as the value for "sup_xref_key" field.
All the operations of a service should contain the same value for identifierNameList. The identifierNameList specified in READ_WITH_IDENTITY operation is used for building the URI for UPDATE, DELETE and PROCESS methods also for the service, because the URI represents the object it is working on, and the READ_WITH_IDENTITY, DELETE, UPDATE and PROCESS methods should work on the same object.
RSE generated RESTful resources operate on retail business payloads. Any payload type used in input/output elements of service def must be a top-level payload, which means that it should be a top-level element of an XSD. For example, SupplierDesc is a top-level payload because it is a top-level element in SupplierDesc.xsd, but SupAttr is not a top-level payload because it is defined as a child element of SupplierDesc. So SupplierDesc can be used to define input/output type in service def, but SupAttr cannot be used for input/output type in service def.
A REST resource/service can work on a simple payload type (e.g., SupplierDesc) or a collection payload type (e.g. SupplierColDesc) or it can have a combination of both. When service has a combination of collection and simple types, the collection payload must be a collection of the simple type that is used in the service. For example, SupplierColDesc is a collection of SupplierDesc, so they can be used in same service.
When a simple type and a collection type are used in same service, then operations should be named appropriately to differentiate between simple and collection type operations. When operation name is not the default name, then the operation name is added in the generated URL.
<operation name="update" operationType="UPDATE">
<input type="SupplierDesc" identifierNameList="supplier_id"/>
<output type="Nothing"></output>
<fault faultType="IllegalArgumentWSFaultException" />
</operation>
<operation name="updateAll" operationType="UPDATE">
<input type="SupplierColDesc" queryParamList="country_id"/>
<output type="Nothing"></output>
<fault faultType="IllegalArgumentWSFaultException" />
</operation>
Based on above servicedef, the generated URLs will be:
/Supplier/{supplier_id}/
/Supplier/updateAll?country_id={country_id}
Every operation must have a valid input and output type defined. Some operations do not need payload body in request. These are HTTP GET and DELETE methods. For operations based on these HTTP methods, the input type can be "Nothing".
"Nothing" is a valid retail payload type and it is used to represent void or empty type in request and response messages
If an operation does not need to return anything in response body, then "Nothing" should be used in output type for that operation.
Operation type NAVIGATE_TO_CHILD is used to GET a child element type of a resource. The child payload must be a top-level payload as well. Following is a sample definition for NAVIGATE_TO_CHILD type:
<service name="CustOrdItm">
<operation name="find" operationType="READ_WITH_IDENTITY" suf-fix="outputType">
<input type="ReferenceId" identifierNameList="id"/>
<output type="CustOrdItmPkVo"></output>
<fault faultType="IllegalArgumentWSFaultException" />
</operation>
<operation name="taxLines" operationType="NAVIGATE_TO_CHILD">
<input type="Nothing" queryParamList="tax_id"/>
<output type="TaxLinePkColVo"></output>
<fault faultType="IllegalArgumentWSFaultException" />
</operation>
</service>
Operation type PROCESS is used to support any business operations which are not CRUD operations. The operation name defined in service def is added in the generated URL and it uses HTTP POST method. Following is a sample definition for PROCESS type:
<operation name="calculateTotal" operationType="PROCESS">
<input type="PayTermDesc" />
<output type="PayTermRef">
</output>
<fault faultType="IllegalArgumentWSFaultException" />
</operation>
Path parameters are the variables which uniquely identify a resource instance. These are used in resource URL to get a resource whose identity matches with the value provided. Below is an example of path param in servicedef xml:
<operation name="find" operationType="READ_WITH_IDENTITY" suffix="outputType">
<input type="Nothing" identifierNameList="sup_xref_key,supplier_id"/>
<output type="SupplierDesc">
</output>
<fault faultType="IllegalArgumentWSFaultException" />
</operation>
The values of path parameters are passed to service provider layer in ServiceOpContext object. The names of properties in ServiceOpContext are prefixed with idParam for path parameters. For example for the above operation the properties in ServiceOpContext will be following:
idParam.sup_xref_key idparam.supplier_id
Query parameters are used for filtering resources based on search criteria. For example, the resource URL Suppliers/searchAll?country_id=10 is to get all suppliers for which country_id is 10. To build such query parameter in URL, queryParamList attribute of input element of operation must contain the parameter names. Below is an example of operation with query parameter:
<operation name="searchAll" operationType="READ_WITH_PREDICATE" suffix="outputType">
<input type="Nothing" queryParamList="customer_type"/>
<output type="CustomerColDesc">
</output>
<fault faultType="IllegalArgumentWSFaultException" />
</operation>
The values of query parameters are passed to service provider layer in ServiceOpContext object. The names of properties in ServiceOpContext are prefixed with queryParam for query parameters. For example for the above operation the properties in ServiceOpContext will be following:
queryParam.customer_type
If service provider wants to return additional links to client in response header, they can set link URLs in ServiceOpContext object. RSE layer looks for properties in ServiceOpContext, and if there are any properties whose name start with link.rel , then RSE builds link URL by appending value to that property to the context path of the service, and if ServiceOpContext contains properties starting with link.url, then it means that it is an external URL and RSE layer will add that URL as-is in the response header.
A service can have relations specified in the outputType of the operation. The name specified in relatedTo element must be the name of a service which exists in the same service def xml.
A service cannot have its own name in relatedTo field.
