4 Working with Service Constructor

This chapter provides an overview of Service Constructor and discusses how to use Service Constructor to create new service solution components.

This chapter includes the following sections:

• Section 4.1, "Introducing Service Constructor"

• Section 4.2, "Using Service Constructor to Create New Service Solution Components"

4.1 Introducing Service Constructor

This section provides an overview of Service Constructor and includes the following topic: Section 4.1.1, "Required Software for Using Service Constructor."

Service Constructor is an extension to Oracle JDeveloper that developers can use to easily create new Oracle Application Integration Architecture (AIA) service component projects that conform to the AIA programming models and naming and architectural recommendations. Presently, Service Constructor supports the following service components:

• Requester Application Business Connector Services (ABCSs)

• Provider ABCSs

As a part of the AIA project lifecycle, Service Constructor can be used in the service construction phase, as shown in Figure 4-1.

Figure 4-1 Overview of the Service Construction Phase of the AIA Project Lifecycle

Service Constructor guides the developer through four of the six sub phases of developing an ABCS. The four sub phases are:

• Define service description and details

  Define high-level information about the service solution component and the project and task to which it belongs.

• Define the service object (or interface)

  Define the type of message that the ABCS should receive and reply.

• Define the target service

  Define the services that should be invoked by the ABCS, and the message it should pass to those services.

• Define additional options and generation point

  Define options such as error-handling and extension run-time location, and the launching point to generate an Oracle JDeveloper project for continued development.

After the developer completes the Service Constructor interview, a complete Oracle JDeveloper project is produced that the developer continues to develop incorporating use case-specific requirements.

Service Constructor enhances developer productivity by providing a more user-friendly interface to the Composite Generator (formerly the Artifact Generator) and auto-inspection of services and project selection from the Project Lifecycle Workbench.

For more information about Project Lifecycle Workbench, see Chapter 3, "Working with Project Lifecycle Workbench."

Service Constructor relieves developers of the time involved in performing repeatable mundane tasks, enabling them to place greater focus on value-added business scenario-specific tasks and thus reducing ABCS development time.

The overall flow for creating a new AIA service component is illustrated in Figure 4-2.

Figure 4-2 Flow for Creating a New AIA Service Component

4.1.1 Required Software for Using Service Constructor

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

• Oracle JDeveloper 11g

• SOA Composite Editor and AIA Service Constructor JDeveloper extensions.

  Both are available through the Oracle JDeveloper Update Center. To access the Update Center, within JDeveloper, navigate to Help > Check For Updates.

  For more information about installing these JDeveloper extensions, see Chapter 2, "How to Set Up JDeveloper for AIA Development."

• FreeMarker 2.3.16 or higher

  You can download the FreeMarker template engine from http://www.freemarker.org. Extract freemarker.jar from the downloaded tar.gz file and place it in your /jdeveloper/jdev/lib folder.

4.2 Using Service Constructor to Create New Service Solution Components

Developers and solution architects regularly collaborate through multiple channels and use documents such as the functional design document to define and communicate the services that must be developed. To begin the development process, the developer should open an existing application workspace or create an application workspace in Oracle JDeveloper.

This section discusses the following topics:

• Section 4.2.1, "Creating a New Service Solution Component Project"

• Section 4.2.2, "Describing the Service"

• Section 4.2.3, "Defining the Service Object"

• Section 4.2.4, "Defining the Target Services"

• Section 4.2.5, "Defining Service Options"

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.

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

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

   Figure 4-3 All Technologies Tab

   
   

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

4. The Service Constructor Welcome screen displays. Select the Skip This Page Next Time option to bypass this page in subsequent visits. Click Next. The Service Description page displays.

4.2.2 Describing the Service

To define the service description:

1. On the Service Description page, click the Import button next to the Name field to access the AIA Resource Browser.

   Use AIA Resource Browser to select the name of an existing service solution component request entered in Project Lifecycle Workbench.

   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, 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 AIA Lifecycle Management or File option for importing a service solution component request.

   Select AIA Lifecycle Management to connect to Project Lifecycle Workbench to retrieve the existing service solution component functional definition.

   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 to select a connection to Project Lifecycle Workbench.

4. Click OK.

5. The Service Solution Component Requests dialog box displays. Select a service solution component from the list of eligible requests. Click OK.

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

   These values were defined by a solution architect while performing a functional decomposition of the service in Project Lifecycle Workbench.

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

   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.

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

9. If necessary, the developer can add to, update, or re-create the information populated to the Service Details page, as shown in Figure 4-4. 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-4 Service Details

   
   

   Table 4-2 Service Detail Elements

   Element	Description
   Service Component	Displays the name of the selected service solution component.
   Service Type	Type of service being created: Provider ABCS or Requester ABCS. Select Application Business Flow if yours is a direct integration.
   Product Code	Defines the associated application.
   System Code	Internal code for use in operations, such as cross-referencing. 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.
   Source Application	Source application in direct integration.
   Application Short Name	Application code, which is also used in naming the connector service. This is defined by the developer.
   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.
   Target Application	Target application in direct integration.

   
   

   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-5. Available fields are discussed in Table 4-3.

Figure 4-5 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-6.

Figure 4-6 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 this flow, we will use the SOA Resource Browser.

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

   Figure 4-7 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-8.

   Figure 4-8 SOA Resource Browser

   
   

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

   Figure 4-9 SOA Resource Browser - WSDL Selection

   
   

5. The Selective Service Operation page display again. In the Operations drop-down list box, select an operation. Click OK.

   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. Available elements are discussed in Table 4-4.

   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.

   Click the CallBack button to access the Call Back dialog box, as shown in Figure 4-10. 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-10 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-11. Define the fault details for the service interface. Available fields are discussed in Table 4-6.

    Figure 4-11 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-12, 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.

Note:

The Service Constructor supports only services that have an exposed interface and cannot directly invoke JCA adapters, such as the File or DB adapter.

Figure 4-12 Target Service Details

Table 4-7 Target Service Detail 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 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 that 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 that this service receives. This value is typically supplied automatically by the service/operation inspection.
Output Message	Message that this service may return. This value is typically supplied automatically by the service/operation inspection.
Output Message Element	Message element as a part of the message that this service may return. This value is typically supplied automatically by the service/operation inspection.
BPEL Scope	Invocation scope that is defined in BPEL. This value is typically supplied automatically by the service/operation inspection.
MessageExchange Pattern	Message exchange pattern of this service. Service Constructor attempts to supply this value by default based on the input/output messages of the service. The choices are Request/Response, Request/Delayed Response, and FireAndForget.
Target is an Application Interface or Target is an Enterprise Business Service	Defines whether invoking an application interface (or service) or an EBS. Service Constructor attempts to supply this value by default based on the directory structure of the service.
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.
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.
Enable WSDL defined fields	This option is deselected by default. Most of the fields are supplied automatically so they are set to uneditable. If for some reason the developer must make a change to one of the preceding fields, selecting this option makes them editable.

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

   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.

   To enable customization of select the Customizable option.

   Click OK.

   Figure 4-13 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-14, where you can define the fault details for the target service. Available fields are discussed in Table 4-8.

   Figure 4-14 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-15, enter service option details. Available fields are discussed in Table 4-9.

   Figure 4-15 Service Options

   
   

   Table 4-9 Service Option Elements

   Element	Description
   Error Handling	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.
   Extensions	WSDL of extension service.
   Custom Fault Policy	Select to be able to create a custom fault policy.
   Customizable	To enable customization select this option.
   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.
   Source Application	Source application in direct integration.
   Target Application	Target application in direct integration.
   Project Name	Displays the name of the project. If you are creating an application business flow, you can edit the project name by clicking the Edit Project Name button.
   Version	Version of the object received by the service.
   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-16, 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-16 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-17, and is ready for further development.

   Figure 4-17 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."