4 Working with Service Constructor

4.1.1 Required Software for Using Service Constructor

Service Constructor requires that presence of the following Oracle and third-party components:

• Oracle JDeveloper 11g

• Oracle SOA Composite Editor and Service Constructor

  Both are available through the Oracle JDeveloper update center. In Oracle JDeveloper, select Help, Check For Updates.

• Freemarker 2.3.15 or higher

  Visit the Freemarker site at http://www.freemarker.org to obtain the Freemarker template engine. Place freemarker.jar (contained in the downloaded zip file) in your <location where AIA Service Constructor was downloaded>/jdev/lib folder found under your Oracle JDeveloper installation.

4.2.1 Creating a New Service Solution Component Project

To create a service solution component project with Service Constructor:

1. In Oracle JDeveloper, open an existing application workspace or create a generic application, as shown in Figure 4-3.

   Figure 4-3 Typical Opening View of a Generic Application in Oracle JDeveloper

   
   

   The developer should then create a project within the Workspace to develop a Project Lifecycle Workbench service solution component.

2. To begin the process of creating a service solution component project, click the New button. The New Gallery dialog box displays, as shown in Figure 4-4.

   Select the All Technologies tab. Select the Business Tier, Application Integration Architecture or General, Projects tree item. Select the AIA Service Component Project list item. Click OK.

   Figure 4-4 All Technologies Tab

   
   

3. The Service Constructor Welcome screen displays, as shown in Figure 4-5. Select the Skip This Page Next Time option to bypass this page in subsequent visits. Click Next. The Service Description page displays.

   Figure 4-5 Welcome to the AIA Service Constructor

   
   

4.2.2 Describing the Service

To define the service description:

1. On the Service Description page, as shown in Figure 4-6, click the Import button to access the AIA Resource Browser.

   Figure 4-6 Import the Service Description

   
   

   Use AIA Resource Browser to select the name of an existing service solution component request entered in Project Lifecycle Workbench by a solution architect or functional product manager.

   This service solution component request represents a request for creation of a new provider or requester Application Business Connector Service (ABCS).

   If the service solution component request is not available from Project Lifecycle Workbench, you can enter the service solution component information directly in Service Constructor. However, Oracle AIA suggests that the functional definition be entered and available from Project Lifecycle Workbench before you start development of a service solution component.

   For more information about creating service solution component requests in Project Lifecycle Workbench, see Section 3.4, "Working with Project Lifecycle Workbench Service Solution Components."

2. AIA Resource Browser displays. Select an option for importing a service solution component request, AIA Lifecycle Management or File, as shown in Figure 4-7.

   Figure 4-7 AIA Resource Browser

   
   

   Most users select AIA Lifecycle Management to connect to Project Lifecycle Workbench to retrieve the service solution component functional definition entered by a solution architect or functional product manager.

   Select the File option to create a service solution component using a previously created XML input file for the AIA 2.x Artifact Generator or the AIA Composite Generator.

   This flow described here illustrates the retrieval of a service solution component request from Project Lifecycle Workbench.

3. Click the Database Connection button to access the Connection dialog box, as shown in Figure 4-8, where you can select a connection to Project Lifecycle Workbench. Click OK.

   Figure 4-8 Connection

   
   

4. The Service Solution Component Requests dialog box displays, as shown in Figure 4-9. Select a service solution component from the list of eligible requests. Click OK.

   Figure 4-9 Service Solution Component Requests

   
   

5. The Service Description page is populated with the name, project, task, and description of the select service solution component.

   Following the AIA lifecycle flow, these values were defined by a solution architect performing a functional decomposition of the service in Project Lifecycle Workbench.

6. If necessary, the developer can add to, update, or re-create the information populated to the Service Description shown in Figure 4-10. Available fields are discussed in Table 4-1. Any additions or changes are later harvested into Oracle Enterprise Repository and Project Lifecycle Workbench.

   Figure 4-10 Service Description Populated from Project Lifecycle Workbench Service Solution Component Request

   
   

   Table 4-1 Service Description Elements

   Element	Description
   Name	Name of the service solution component.
   Project	Name of the project that contains the task that contains the service solution component.
   Task	Task that contains the service solution component request.
   Description	Details about the requested service solution component, including its purpose.

   
   

   Click Next.

7. The Service Details page displays. Define information about the associated application, and the type of service that is being created.

   Product Code, Industry, and Service Type values typically come from Project Lifecycle Workbench, if an existing service solution component request was selected to access this page.

8. If necessary, the developer can add to, update, or re-create the information populated to the Service Details page, as shown in Figure 4-11. Available fields are discussed in Table 4-2. Any additions or changes are later harvested into Oracle Enterprise Repository and Project Lifecycle Workbench.

   Figure 4-11 Service Details

   
   

   Table 4-2 Service Detail Elements

   Element	Description
   Service Component	Displays the name of the selected service solution component.
   Product Code	Defines the associated application.
   Application Name	User-friendly name assigned to the application for which the connector service is being created. This is defined by the developer.
   Application ID	Internal code for use in operations, such as cross-referencing. This is defined by the developer.
   Application Short Name	Application code, which is also used in naming the connector service. This is defined by the developer.
   Industry	Industry to which the connector service applies, such as Insurance, Banking, Utilities, and so on. Select Core, if the connector service is not associated with a particular industry.
   Service Operation	Defines the verb of the service, such as Create, Update, Delete, Sync, Validate, Process, or Query. This is defined by the developer.
   Service Version	Version of the service. This is defined by the developer.
   Service Type	Type of service being created: Provider ABCS or Requester ABCS.

   
   

   Click Next to access the Service Object page where you define the inbound message that the service receives. Service objects are also typically referred to as service interfaces. This document refers to them as service objects. Service Constructor leverages service inspection to learn about the message.

4.2.3 Defining the Service Object

After defining the service description, the developer should define the service object, also known as the service interface, to be handled by the ABCS. This is the information about the type of message that is received, which is different based on the type of ABCS.

Requester ABCSs connect participating applications to an Enterprise Business Service (EBS) to enable the application to invoke the EBS. These services receive an Application Business Message (ABM) and produce an Enterprise Business Message (EBM).

Provider ABCSs, however, connect applications to an EBS to enable the EBS to invoke a service provided by the participating applications.

This section includes the following topics:

• Section 4.2.3.1, "Defining the Service Object for a Requester ABCS"

• Section 4.2.3.2, "Defining the Service Object for a Provider ABCS"

4.2.3.1 Defining the Service Object for a Requester ABCS

Define the service object for a requester ABCS on the Service Object page accessed for a service type of Requester ABCS, as shown in Figure 4-12. Available fields are discussed in Table 4-3.

Figure 4-12 Service Object Definition for a Requester ABCS

Table 4-3 Service Object Elements for a Requester ABCS

Element	Description
Schema (XSD)	Path to the XML schema definition (XSD) for the message that is received by the service.
Namespace	A reference in the form of a URL that uniquely identifies the attributes of the service object.
Prefix	Used to associate attributes with this service.
Input Message	Name of the message that is received by the service.
Output Message	Name of message that is returned by the service. Typically, this is used in the request-reply message exchange pattern.
Object Name	Name of the object (noun) that is received by the service.
Version	Version of the object received by the service.
Message Exchange Pattern	Message exchange pattern implemented by the service, such as Request/Reply, Request/Delayed Response, or Fire and Forget.
CallBack	If the service is implementing a Request/Delayed Response message exchange pattern, the CallBack button displays.

4.2.3.2 Defining the Service Object for a Provider ABCS

Define the service object for a provider ABCS on the Service Object page, as shown in Figure 4-13.

Figure 4-13 Service Object Definition for a Provider ABCS

Available fields are discussed in Table 4-4. The service object for a provider ABCS requires the same types of attributes contained in a requester ABCS, however the message being received is an EBM.

Because all AIA EBSs are available through Oracle Metadata Services (MDS), the WSDLs for the services are also available. Service Constructor can inspect a service and learn about the corresponding message.

To inspect a service and learn about the corresponding message:

1. On the Service Object page accessed for a service type of Provider ABCS, click the Select Service Operation button to access the Select Service Operation dialog box, where you can select the WSDL, or operation, that invokes the service.

   With the services and schemas being served from MDS, the SOA Resource Browser is typically used to select the appropriate WSDL.

   For more information about creating MDS connections, see Section 2.1.1, "How to Set Up JDeveloper for AIA Development."

   Alternatively, if the WSDL is external and accessible as a URL, such as with a remote service provider, the URL can be pasted directly into the Select WSDL field. Then, click the Reload button to inspect the WSDL.

   For the purposes of this flow, we will use the SOA Resource Browser.

2. In the Select Service Operation dialog box, as shown in Figure 4-14, click the Resource Browser button to select the WSDL.

   Figure 4-14 Select Service Operation

   
   

3. The SOA Resource Browser dialog box displays. In the File System drop-down list box, select Resource Palette, as shown in Figure 4-15.

   Figure 4-15 SOA Resource Browser

   
   

4. Expand the SOA-MDS tree item, as shown in Figure 4-16. Navigate to and select the WSDL for the service that invokes the service component you are creating. Click OK.

   Figure 4-16 SOA Resource Browser - WSDL Selection

   
   

5. The Selective Service Operation - Operation Selected page displays, as shown in Figure 4-17. In the Operations drop-down list box, select an operation. Click OK.

   Figure 4-17 Select Service Operation - Operation Selected

   
   

   Service Constructor inspects the selected service and, in most cases, supplies most of the attributes by default. The developer only needs to define the object name and version.

   If the developer must access any of the fields that were automatically populated, such as to make a correction, select the Enable WSDL defined fields option.

6. The Service Object page is populated with the WSDL information, as shown in Figure 4-18. Available elements are discussed in Table 4-4.

   Figure 4-18 Service Object Definition for a Provider ABCS - WSDL Information Populated

   
   

   Table 4-4 Service Object Elements for a Provider ABCS

   Element	Description
   WSDL (optional)	The calling service WSDL is used by the Service Constructor to inspect and automatically supply most of the values by default.
   Schema (XSD)	Schema definition of the message type being used by the calling service to call the service interface. This value is typically supplied automatically by the service/operation inspection. The browser button is available if the developer needs to browse for the appropriate object in MDS.
   Namespace	Namespace of the underlying object. This value is typically supplied automatically by the service/operation inspection.
   Prefix	Prefix to be used as a reference for the message that is received from the calling service. This value is typically supplied automatically by the service/operation inspection.
   Input Message	Message that is received from the calling service. This value is typically supplied automatically by the service/operation inspection.
   Output Message	Message with which this service may respond to the calling service. This value is typically supplied automatically by the service/operation inspection.
   Object Name	Name of the underlying object used in the service invocation. This value is typically supplied automatically by the service/operation inspection.
   Version	Version of the underlying object. This value is typically supplied automatically by the service/operation inspection.
   Message Exchange Pattern	Message exchange pattern being used. This value is typically supplied automatically by the service/operation inspection based on a series of rules.
   Enable WSDL defined fields	In most cases, most or all of the attributes are supplied automatically by the service/operation inspection. If an attribute is not supplied automatically, is supplied incorrectly, or the developer must change any of the values, select this option to make all fields editable.

   
   

7. If the service being created is following a Request/Delayed Response message exchange pattern, the CallBack button displays on the Service Object page, as shown in Figure 4-19.

   Figure 4-19 CallBack Button

   
   

   Click the CallBack button to access the Call Back dialog box, as shown in Figure 4-20. Define the target service that should be invoked by the service being created here as a delayed response. Available fields are discussed in Table 4-5.

   Figure 4-20 Call Back Details

   
   

   Table 4-5 Call Back Elements

   Element	Description
   WSDL	Click the WSDL Inspector button to view a list of the operations. Select the WSDL that invokes the service. You can also use services that are not in MDS or in the local file system, but which are accessible through a URL. If the URL to the service is in the buffer, paste it into the Select WSDL field. After the WSDL is selected, click the Reload button.
   Service NameSpace	Namespace of the service. This value is typically supplied automatically by the service/operation inspection.
   Service NameSpace Prefix	Prefix used to reference the namespace. This value is typically supplied automatically by the service/operation inspection.
   Input Message	Message this service receives. This value is typically supplied automatically by the service/operation inspection.
   Input Message Element	Message element as a part of the message this service receives. This value is typically supplied automatically by the service/operation inspection.
   BPEL Scope	Invocation scope defined in BPEL. This value is typically supplied automatically by the service/operation inspection.
   Schema (XSD)	Underlying schema definition of the service. This value is typically supplied automatically by the service/operation inspection.
   Object Name	Name of the object. This value is typically defined by the developer.
   Version	Version of the schema definition. This value is typically defined by the developer.
   NameSpace	Namespace of the underlying schema definition. This value is typically supplied automatically by the service/operation inspection.
   Prefix	Prefix by which the namespace is referenced. This value is typically supplied automatically by the service/operation inspection.

   
   

8. Click OK in the Call Back dialog box.

9. Click Next on the Service Object page.

10. The Service Object Fault Details page displays as shown in Figure 4-21. Define the fault details for the service interface. Available fields are discussed in Table 4-6.

    Figure 4-21 Service Object Fault Details

    
    

    Table 4-6 Service Object Fault Detail Elements

    Element	Description
    Fault Schema Location	Schema definition for the fault message. This value is typically supplied automatically by the service/operation inspection based on common error definition.
    Fault Namespace	Namespace for the fault message. This value is typically supplied automatically by the service/operation inspection.
    Fault Namespace Prefix	Prefix to be used as a reference for the fault message. This value is typically supplied automatically by the service/operation inspection.
    Fault Message Element	Element definition of the fault message. This value is typically supplied automatically by the service/operation inspection.

    
    

11. Click Next to access the Target Service Details page.

4.2.4 Defining the Target Services

After the service description and service object are complete, define the target service invocations.

On the Target Service Details page, as shown in Figure 4-22, select the target services that should be invoked. Available fields are discussed in Table 4-7. Here the WSDL is used to not only inspect and supply the underlying object attributes, but also to be included in part of the service definition.

Figure 4-22 Target Service Details

To define the target services:

1. On the Target Service Details page, click the Options button to access the Target Service Options dialog box, as shown in Figure 4-23.

   Target service options such as the Composite Application Validation System (CAVS) and the reference WSDL creation are enabled by default. If an extension service is used, enable it here. Click OK.

   Figure 4-23 Target Service Options

   
   

2. On the Target Service Details page, click Next to access the Target Service Fault Details page, as shown in Figure 4-24, where you can define the fault details for the target service. Available fields are discussed in Table 4-8.

   Figure 4-24 Target Service Fault Details

   
   

   Table 4-8 Target Service Fault Detail Elements

   Element	Description
   Fault Schema Location	Defines the schema of the fault message that may be returned. This value is typically supplied automatically by the service/operation inspection.
   Fault Namespace	Defines the name space of the fault schema. This value is typically supplied automatically by the service/operation inspection.
   Fault Namespace Prefix	Defines the prefix by which elements are attributed to the namespace. This value is typically supplied automatically by the service/operation inspection.
   Fault Message	Message that may be returned in a fault. This value is typically supplied automatically by the service/operation inspection.
   Fault Message Element	Element within the message that may be returned in a fault. This value is typically supplied automatically by the service/operation inspection.

   
   

3. Click Next to access the Service Options page.

4.2.5 Defining Service Options

To define service options:

1. On the Service Options page, as shown in Figure 4-25, enter service option details. Available fields are discussed in Table 4-9.

   Figure 4-25 Service Options

   
   

   Table 4-9 Service Option Elements

   Element	Description
   Add ErrorHandling	Option to add error handling. The default value is TRUE.
   Error Handling Service Runtime Location	Designate the runtime location of the AIAAsyncErrorHandlingBPELProcess service. The default location is the common oramds:/ location. If you select the AIAAsyncErrorHandlingBPELProcess service WSDL location in the MDS infrastructure library, perform the post-service-generation task described following this table. If you select the actual runtime endpoint location value of AIAAsyncErrorHandlingBPELProcess, no post-service-generation task is required.
   Add Extensions	Option to add extensions. If the Enable Extension option is enabled under the Target Service options, then this option is selected by default and is required.
   Extension WSDL Runtime Location	WSDL of extension service.
   Generate custom fault policy	Select to be able to create a custom fault policy.
   Additional Target	Click to add an additional target. Certain participating applications require calls to multiple service interfaces to complete the necessary steps for message transformation (message enrichment, and so on).

   
   

   If you have selected the AIAAsyncErrorHandlingBPELProcess service WSDL location in the MDS infrastructure library as the Error Handling Service Runtime Location value, perform the following post-service-generation task:

   1. Access the generated composite to update the location attribute of the binding.ws element within the reference element for AIAAsyncErrorHandlingBPELProcess.

   2. Update the location with the actual AIAAsyncErrorHandlingBPELProcess runtime location. For example, the location indicated in bold in Example 4-1, must be updated.

   Example 4-1 Reference Element for AIAAsyncErrorHandlingBPELProcess

   <reference ui:wsdlLocation="oramds:/apps/AIAMetaData/AIAComponents/
   InfrastructureServiceLibrary/V1/wsdls/AIAAsyncErrorHandlingBPELProcess.wsdl"
   name="AIAAsyncErrorHandlingBPELProcess">
   ...
      binding.ws port="http://xmlns.oracle.com/AIAAsyncErrorHandlingBPEL
   Process#wsdl.endpoint(AIAAsyncErrorHandlingBPELProcess/AIAAsyncError
   HandlingBPELProcess)" location="oramds:/apps/AIAMetaData/AIAComponents/
   InfrastructureServiceLibrary/V1/wsdls/AIAAsyncErrorHandlingBPELProcess.wsdl"
   xmlns:ns="http://xmlns.oracle.com/sca/1.0"/>
   ...
   </reference>
   

2. If an additional target is needed, click the Additional Target button on the Service Option page to access the Create Additional Target dialog box, as shown in Figure 4-26, where you can add another invocation for an application that cannot support the EBM through only one invocation.

   For example, take a scenario in which updating a Person in a participating application may require an invocation to both a Person and an Address service.

   Figure 4-26 Create Additional Target

   
   

   This dialog box contains the same attributes and features as the primary target dialog box, but consolidates the service details, fault details, and options.

   The details for the additional target are completed in the same manner discussed for the Target Service Details page, discussed in Section 4.2.4, "Defining the Target Services".

3. Optionally, click the Save As button to save a service solution component request input file. Saving the input file allows it to be used with the command line-based Composite Generator, if desired, or for troubleshooting of the Service Constructor.

4. Click Finish.

   The ABCS composite has been created, as shown in Figure 4-27, and is ready for further development.

   Figure 4-27 Example of the ABCS Composite

   
   

   After service construction is completed, you can choose to perform harvesting of your design-time composites into the Project Lifecycle Workbench and optionally, to Oracle Enterprise Repository.

   For more information, see Section 5.2, "Harvesting Design-Time Composites into Project Lifecycle Workbench and Oracle Enterprise Repository."