19 Working with Service Constructor

This chapter includes the following sections:

Section 19.1, "Introducing Service Constructor"
Section 19.2, "Using Service Constructor to Create New Service Solution Components"

19.1 Introducing Service Constructor

This section provides an overview of Service Constructor and includes the following topic: Section 19.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 19-1.

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

This image is described in surrounding text

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

Define service description and details

Define high-level information about the service solution component and the project and business task to which it belongs.
Define the service object (or interface)

Define the type of message that the ABCS will receive and if and how it will reply.
Define the target service

Define the services that will be invoked by the ABCS, and the message it will pass to those services.
Define additional options and generation point

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

Once the developer has completed the Service Constructor interview, a complete Oracle JDeveloper project is produced that the developer will continue 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 2, "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 19-2.

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

19.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 jdeveloper/jdev/lib folder found under your Oracle JDeveloper installation.

19.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 need to be developed. To begin the development process, the developer will open an existing application workspace or create a new application workspace in Oracle JDeveloper.

This section discusses the following topics:

Section 19.2.1, "Creating a New Service Solution Component Project"
Section 19.2.2, "Describing the Service"
Section 19.2.3, "Defining the Service Object"
Section 19.2.4, "Defining the Target Services"
Section 19.2.5, "Defining Service Options"

19.2.1 Creating a New Service Solution Component Project

To create a new service solution component project with Service Constructor:

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

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

The developer will then create a new project within the Workspace to develop a Project Lifecycle Workbench service solution component.
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 19-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 19-4 All Technologies Tab
The Service Constructor Welcome screen displays, as shown in Figure 19-5. Select the Skip This Page Next Time option to bypass this page in subsequent visits. Click Next. The Service Description page displays.

Figure 19-5 Welcome to the AIA Service Constructor

19.2.2 Describing the Service

To define the service description:

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

Figure 19-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, we strongly suggest 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 2.4, "Working with Project Lifecycle Workbench Service Solution Components."
AIA Resource Browser displays. Select an option for importing a service solution component request, AIA Lifecycle Management or File, as shown in Figure 19-7.

Figure 19-7 AIA Resource Browser

Most users will select AIA Lifecyle 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.
Click the Database Connection button to access the Connection dialog box, as shown in Figure 19-8, where you can select a connection to Project Lifecycle Workbench. Click OK.

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

Figure 19-9 Service Solution Component Requests
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.

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

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

Table 19-1 Service Description Elements

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

Click Next.

The Service Details page displays. Define information about the associated application, as well as 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.

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

Figure 19-11 Service Details

Table 19-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. Ths 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 will define the inbound message that the service will receive. Service objects are also typically referred to as service interfaces. This document will refer to them as service objects. Service Constructor leverages service inspection to learn about the message.

19.2.3 Defining the Service Object

After defining the service description, the developer will define the service object, also known as the service interface, to be handled by the ABCS. This is the information about what type of message will be 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, on the other hand, 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 19.2.3.1, "Defining the Service Object for a Requester ABCS"
Section 19.2.3.2, "Defining the Service Object for a Provider ABCS"

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

Figure 19-12 Service Object Definition for a Requester ABCS

Table 19-3 Service Object Elements for a Requester ABCS

Element	Description
Schema (XSD)	Path to the XML schema definition (XSD) for the message that will be 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 will be received by the service.
Output Message	Name of message that will be 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.

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

Figure 19-13 Service Object Definition for a Provider ABCS

Available fields are discussed in Table 19-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:

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 will invoke 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 20.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.
In the Select Service Operation dialog box, as shown in Figure 19-14, click the Resource Browser button to select the WSDL.

Figure 19-14 Select Service Operation
The SOA Resource Browser dialog box displays. In the File System drop-down list box, select Resource Palette, as shown in Figure 19-15.

Figure 19-15 SOA Resource Browser
Expand the SOA-MDS tree item, as shown in Figure 19-16. Navigate to and select the WSDL for the service that will invoke the service component you are creating. Click OK.

Figure 19-16 SOA Resource Browser - WSDL Selection
The Selective Service Operation - Operation Selected page displays, as shown in Figure 19-17. In the Operations drop-down list box, select an operation. Click OK.

Figure 19-17 Select Service Operation - Operation Selected

Service Constructor inspects the selected service and, in most cases, will be able to supply most of the attributes by default. The developer will then simply have to define the object name and version.

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

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

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

Table 19-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 will be received from the calling service. This value is typically supplied automatically by the service/operation inspection.
Input Message	Message that will be 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 needs to change any of the values, select this otion to make all fields editable.

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

Figure 19-19 CallBack Button

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

Figure 19-20 Call Back Details

Table 19-5 Call Back Elements

Element	Description
WSDL	Click the WSDL Inspector button to view a list of the operations. Select the WSDL that will invoke 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. Once 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.

Click OK in the Call Back dialog box.
Click Next on the Service Object page.

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

Figure 19-21 Service Object Fault Details

Table 19-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.

Click Next to access the Target Service Details page.

19.2.4 Defining the Target Services

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

On the Target Service Details page, as shown in Figure 19-22, you will select the target services that will be invoked. Available fields are discussed in Table 19-7. Here the WSDL will be used to not only inspect and supply the underlying object attributes, but will also 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 19-22 Target Service Details

Table 19-7 Target Service Detail Elements

Element	Description
WSDL	Click the WSDL Inspector button to view a list of the operations. Select the WSDL that will invoke 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, you can paste it into the Select WSDL field. Once 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.
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.
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 needs to make a change to one of the preceding fields, selecting this option will make them editable.

To define the target services:

On the Target Service Details page, click the Options button to access the Target Service Options dialog box, as shown in Figure 19-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 19-23 Target Service Options

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

Figure 19-24 Target Service Fault Details

Table 19-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 will be 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.

Click Next to access the Service Options page.

19.2.5 Defining Service Options

To define service options:

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

Figure 19-25 Service Options

Table 19-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, you must 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 more than one service interface 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:

Access the generated composite to update the location attribute of the binding.ws element within the reference element for AIAAsyncErrorHandlingBPELProcess.
Update the location with the actual AIAAsyncErrorHandlingBPELProcess runtime location. For example, the location indicated in bold in Example 19-1, must be updated.

Example 19-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>

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 19-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 19-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 19.2.4, "Defining the Target Services".
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.
Click Finish.

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

Figure 19-27 Example of the ABCS Composite

Once service construction is complete, 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 3.2, "Harvesting Design-Time Composites into Project Lifecycle Workbench and Oracle Enterprise Repository."