6 Service Definition Library XML File

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.

Schema Definition

This section discusses the elements of the schema, beginning with the root element and including child elements.

serviceProviderDefLibrary

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>

Attributes

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.

Elements

The serviceProviderDefLibrary contains the following elements:

service

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.

Managing the Service Definition Library XML File

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.

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

Changing the Version of the File

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>

Changing the appName Attribute in the File

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>

Renaming a Service or Operation Name in the File

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.

Adding a New Service or New Operation to the File

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>

Deleting a Service or Deleting Operations from the File

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.

Defining New Exceptions to the Operations

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>

Using Different Versions of Objects as Input/Output to an Operation

The version difference between objects does not impact the RSE tool, as long as the objects adhere to standards.