Components

Figure 9.4 illustrates a component. Listing 9.3 shows the previously described component element within a composite element.

Listing 9.3: ProcessQuoteComponent within a composite element

 <composite name="QuoteComposite">    .    .    <component name="ProcessQuoteComponent" requires="confidentiality">       <implementation.bpel name="ProcessQuoteImplementation" />       <service name="ProcessQuote">          <interface.partnerLinkType            type="ProcessQuotePLT"            serviceRole="ProcessQuoteRole" />          <binding.sca/>       </service>       <property name="availableDiscount" many="true">Auto Club</property>       <reference name="calculateOne"                  target="CalculateOneComponent" />       <reference name="calculateTwo"                  target="CalculateTwoComponent" />    </component>    <component name="CalculateOneComponent">       .       .    </component>    <component name="CalculateTwoComponent">       .       .    </component> </composite> 

Figure 9.4: Component

Let's review several aspects of the definition, starting with the requires attribute, which identifies a list of policy intents, although only one intent is specified in the example.

An interaction intent such as confidentiality applies to descendant elements that provide binding details; in this case, those elements (of type service and reference) specify the SCA binding explicitly or by default. In contrast, an implementation intent such as logging applies to the subordinate implementation element, which identifies which business logic to run when the component is invoked. The presence of a policy intent at a relatively high-level element in any SCA definition makes the intent available to every subordinate element where the intent applies.

A component service identifies a set of operations provided by the implementation. The operations can be made available to other components in the same composite and to software that is outside the composite. Included in this example are the details necessary to access the service: an interface description and a binding (in this case, the SCA binding).

 <service name="ProcessQuote">    <interface.partnerLinkType       type="ProcessQuotePLT"       serviceRole="ProcessQuoteRole" />    <binding.sca/> </service> 

A component property defines a relationship with a variable in the implementation. Specifically, a property has a name and, optionally, an XSD element or data type. (In this example, the data type is identified in the implementation.)

 <property name="availableDiscount" many="true">Auto Club</property> 

The property lets you set the initial value of the corresponding implementation variable. In most cases, the property name is the same as the variable name. You can also assign that value from a file or from a property that resides in an enclosing composite.

If the variable in the code accepts a list of values, SCA allows multiple property elements with the same name. As suggested in the following example (from an application at Highlight Insurance), the ProcessQuoteComponent implementation has a variable that holds a list of discounts (for Automobile Club membership, employee status, and so on); and the logic of that code decides which of the discounts will apply to a given applicant.

 <component name="ProcessQuoteComponent">    .    .    <property name="availableDiscount">       <value>Auto Club</value>       <value>Employee</value>    </property>  </component> 

The available discounts often vary. By setting the values in property elements of a component definition instead of in the code, the company avoids having to update the code each time a change is required to the discount list.

A component reference is a set of operations that are external to the implementation. The ultimate effect of assigning a value to the reference is that you specify the binding detail needed to invoke an operation at a specific endpoint.

The set of operations can be in another component in the same composite. In this case, the SCA assembler assigns the name of a component as the value of the target attribute.

 <reference name="calculateOne"            target="CalculateOneComponent" /> 

Alternatively, the set of operations can be in software that is outside the composite. In this case, the SCA assembler or deployer promotes the component reference; that is, he or she identifies the component reference in a composite reference, which (as shown later) is another definition in the same composite.

An implementation may be coded to handle a multi-valued reference, which is a reference that provides a list of target services. Your implementation might use a multi-valued reference, for example, to retrieve prices for the same kind of product from several vendors:

 <reference name="vendors"            target="VendorReference01 VendorReference02"/> </reference> 

By setting values in a component reference instead of in the code, the company avoids updating the code whenever a change is required in the vendor list.

The next sections further describe properties, services, and references of a component. We focus on the relationship (or mapping) of a given kind of configurable value and a construct in the implementation. In brief:

• A service is one of the sets of operations that the code makes available to a requester.

• A property is mapped to a variable that is used in data manipulation.

• A reference is mapped to a variable that provides access to a set of operations external to the component.

We include details for BPEL and Java. A BPEL process that uses SCA properties and multi-valued references requires an extension element and special syntax. SCA can handle a traditionally coded process, however, if you don't need those SCA capabilities. The extension element is as follows.

 <process>    <extensions>       <extension          namespace="http://www.osoa.org/xmlns/sca/bpel/1.0"          mustUnderstand="yes"/>    </extensions> </process> 

The mustUnderstand attribute indicates that the BPEL engine must be able to process the SCA detail.

We include Java-specific details because an early goal for Service Component Architecture was to map SCA constructs to that language. If you are unfamiliar with Java, you can skim or skip the details.

When you realize that the code written for an SCA runtime can include details that are specific to SCA, you may ask, "Why are there SCA-specific details in code? Is there a requirement that the business logic be deployed only when an SCA runtime is in use?"

The SCA details in the code help an SCA runtime apply configuration values. In many cases, however, the SCA-specific details are optional or can be specified in a separate file, and the presence of those details does not stop you from deploying the same code outside an SCA runtime.

Defining Services in Implementation Code

An SCA service is a service-interface description. Here are examples:

• In relation to a BPEL process (and for reasons we'll describe), the name of a service is the name of a partner link - specifically, a partner link that defines a conversation initiated by the partner service. The partner link may be assigned to a receive activity, to an onMessage event in a pick activity, or to an OnEvent event in an event handler.

• In relation to a Java class, a service is a Java interface being implemented by the class; or, if the Java class is not explicitly implementing a Java interface, a service is the set of all public methods in the class. In most cases, you identify a service by including, in the Java code, the SCA-specific annotation @Service.

If your implementation has only one service, you have no decision to make in relation to services. If your implementation has multiple services, however, you can select which services to expose; that is, you can select which sets of operations can be accessed. Even a component without a service can do useful work - for example, by acting as a timer that submits a message a few seconds after a composite is invoked.

Let's consider the relationship of a BPEL partner link to a port type. Here are excerpts from a process.

 <process>    <partnerLinks>       <partnerLink name="ProcessQuote"                    myRole="ProcessQuoteRole"                    partnerLinkType="ProcessQuotePLT" />    </partnerLinks>    <sequence>       <receive createInstance="yes"                partnerLink="ProcessQuote"                operation="placeQuote"                variable="quoteRequest">       </receive>       .       .       .    </sequence> </process> 

As described in Chapter 7, a partner link is based on a partner link type and indicates which role is enacted by the BPEL process, which role is enacted by the partner service, or both.

The presence of the attribute myRole in the partner link ProcessQuote means that the BPEL process is making operations available to the partner service. Here's the related partner link type, which is outside the process.

 <partnerLinkType name="ProcessQuotePLT">    <role name="ProcessQuoteRole">      <portType name="ProcessQuotePT" />    </role> </partnerLinkType> 

The portType element in that partner link type identifies the operations that can be accessed by way of the partner link.

Here's what our declarations tell us:

• An SCA service ProcessQuote is named for the partner link referenced in the receive activity.

• The port type ProcessQuotePT describes the operations provided by the SCA service.

Mapping of Properties to Implementation Code

A property in a component is mapped to a data area in an implementation. A property that provides a list of values is mapped to an array or to a similar, language-specific collection variable.

Here are language-specific details:

• In relation to a BPEL process, an SCA property is mapped to a BPEL variable that has an SCA-specific property attribute set to yes. Here's an example.

   <process name="ProcessQuote">    .    .    <variable name="availableDiscount"              type="xsd:string"              sca:property="yes"/> </process> 

• In relation to a Java class, a property is mapped to a Java object or primitive variable. In most cases, you identify the variable by including the SCA-specific @Property annotation in the Java code. Here's an example.

   @Property public String availableDiscount; 

Mapping of References to Implementation Code

A reference in a component is mapped to a variable that provides access to external operations. A reference that provides a list of endpoint references is mapped to an array or to a similar, language-specific collection variable.

Here are language-specific details:

• In relation to a BPEL process, the mapping depends on whether the reference contains a single endpoint reference or a list. A single-valued reference is mapped to a partner link - specifically, to a partner link whose first runtime use is to send data from the process. The most common example is a partner link used in an invoke activity.

  As shown later, a multi-valued reference is mapped to a variable that holds multiple entries. Each run of a forEach activity, for example, can copy an endpoint reference from the variable to a partner link and then use the partner link in an invoke activity. The activity might elicit a price from one or another vendor.

  Assignment of an endpoint reference always applies to the partner role of a partner link; in other words, the assignment is used when accessing operations that are external to the component.

• In relation to a Java class, a reference is mapped to a Java interface whose methods are invoked. In most cases, you identify a reference by including, in the Java code, the SCA-specific annotation @Reference.

Let's look more closely at how SCA supports multi-valued references in BPEL. Our example is from the OSOA document SCA Client and Implementation Model Specification for WS-BPEL.

First of all, the support relies on serviceReferenceList, an XSD element declaration provided by SCA.

 <xsd:element name="serviceReferenceList">    <xsd:complexType>       <xsd:sequence>          <xsd:element ref="sref:service-ref"                       minOccurs="0" maxOccurs="unbounded"/>       </xsd:sequence>    </xsd:complexType> </xsd:element> 

The referenced type (sref:service-ref) is provided with BPEL and conforms to whatever data is required to describe a particular kind of endpoint reference. The important point is that a series of endpoint references is made available to a BPEL variable.

 <variable name="vendors" element="sca:serviceReferenceList">    <sca:multiReference partnerLinkType="vendorPT"                        partnerRole="vendor" /> </variable> 

That BPEL variable is based on sca:serviceReferenceList, includes the SCA extension element sca:multiReference, and is referenced in a partnerLink element, in the SCA-provided attribute sca.multiRefFrom.

Listing 9.4 shows an outline of a forEach activity that uses a list of endpoint references.

Listing 9.4: forEach activity outline

 <forEach counterName="idx" ...>    <startCounterValue>1</startCounterValue>    <finalCounterValue>       count($vendors/sref:service-ref)    </finalCounterValue>    .    .    <scope>    .    .       <partnerLink name="vendorLink"                    partnerLinkType="vendorPT"                    myRole="quoteRequester"                    partnerRole="vendor"                    sca:multiRefFrom="vendors" />         .         .       <assign>          <copy>             <from>$vendors/sref:service-ref[$idx]</from>              <to partnerLink="vendorLink" />           </copy>        </assign>          .          .    </scope> </forEach> 

Component Types

The component type is a characteristic of the implementation, describing the configurable aspects of the implementation, with details that are independent of the specific values that will be set at configuration time. The component type has several purposes:

• The SCA assembler uses the component type to identify what services are exposed and what properties and references are available.

• The SCA runtime uses the component type first, to verify that the assembler tried to access only the exposed services and tried to set only the available references and properties; and second, to assign the values that the integrator set for properties and references.

• Last, if your company develops its services from the top down (first designing a component, then writing the related implementation code), project managers can use an XML-based componentType file for design validation. First, the designer sends the developer a componentType file. Later, if the SCA runtime has access to the component and to the original componentType file and does not issue an error, your company knows that the developer fulfilled at least some of the designer's intent; specifically, the company has ensured that the interfaces and variables in the code do not conflict with those in the component type.

Our review of component-type details suggests a general characteristic of SCA. You can specify details in the implementation and can change, supplement, or restrict those details at a higher level.

Three kinds of details are involved. First, the details for each component service include the name and interface and may include a list of policy intents and a list of valid bindings. Second, the details for each component property include the name and type; an indicator of whether a property value is required; an indicator of whether multiple property values are valid; and optionally, a default value (for a single-valued property) or one or more default values (for a multi-valued property). Last, the details for each component reference include the name and interface; may include a list of policy intents and a list of valid bindings; and indicate whether a reference value is required and whether multiple reference values are valid.

The SCA runtime tries to determine the component type by inspecting the implementation code. If the SCA runtime cannot determine all details, you must supply additional information in a componentType file. If that file has details that contradict the implementation code, an error occurs at run time.

ComponentType File

We'll give you a sense of the content of a componentType file by showing you an excerpt (Listing 9.5), which we've formatted for easy reading.

Listing 9.5: componentType file excerpt

 <componentType>    <service name="ProcessQuote" requires="confidentiality">        <!- in relation to a BPEL process, the preferred form             of interface declaration refers to the partner link             type, not to the partner link and not (as in the             later references) to the WSDL port type ->        <interface.partnerLinkType          type="ProcessQuotePLT"          serviceRole="ProcessQuoteRole" />    </service>    <!- includes a default value ->    <property name="availableDiscount" type="xsd:string"              many="true" required="false">Auto Club</property>    <reference name="calculateOne" multiplicity="1..1">       <interface.wsdl          interface=             "http://com/highlight/ProcessQuote#             wsdl.interface(calculateOne)" />    </reference>    <reference name="calculateTwo" multiplicity="1..n">       <interface.wsdl          interface=               "http://com/highlight/ProcessQuote#               wsdl.interface(calculateTwo)" />    </reference> </componentType> 

Additional Details on Properties and References

The details in this section are useful for both elementary and advanced uses. First, consider two attributes of the property element in a componentType file:

• many indicates whether a list of values is acceptable. The default value is false.

• required indicates that a property value is needed from the component definition in the composite file or, as described later, from a higher-level composite.

  Use of a default value (in this case, Auto Club) is not appropriate when the property value is required. The value of required in this example, however, is false, which is the default.

Second, consider the multiplicity attribute of the reference element. That attribute indicates whether the reference is required and whether the reference provides a single value or a list. The valid values are as follows:

• 1‥1 (the default) means the reference is required and can provide only one value.

• 1‥n means that the reference is required and can provide multiple values. For example, the component might request price quotes from multiple vendors, with a runtime failure if no vendor is specified.

• 0‥1 means that the reference is optional and can provide only one value. For example, the component might send log data to a standard destination if one is available.

• 0‥n means that the reference is optional and can provide multiple values. For example, the component might send data to zero-to-many subscribers.