7 Using Data Providers to Retrieve Data

This chapter describes how to use data providers to retrieve data when modeling orders in Oracle Communications Order and Service Management (OSM).

About Data Providers and Adapters

An Oracle Communications Design Studio data provider is an instantiation of adapter (which is a Java class) that can retrieve data in an XML format from external systems. Data Providers are used when defining Data Instance behaviors. Design Studio provides several built-in Data Providers to retrieve external XML instances from specific sources such as an Objectel server extension or a SOAP web service. Additionally, you can create your own custom Data Provider (see "Custom Data Providers" for more information).

In Design Studio, the Data Provider editor Settings tab (Figure 7-1) allows you to set the Data Provider type using Provider Type. Types of Data Providers include:

Objectel
Order
Property File
SOAP
XML Attachment
XML File
XML Validation
JDBC
Web Service
Custom Data Providers

When you select any of the above choices other than a custom data provider, the Provider Class field becomes disabled and is populated with the OSM implementation of the adapter. When you select Custom, the Provider Class field is enabled because you must supply the class name of the custom adapter that you write. See "Custom Data Providers" for detailed information.

Figure 7-1 Data Provider Settings Tab

Data Provider Interface Tab

Data providers, both built-in and custom, can take parameters as input, as shown in the Interface tab (Figure 7-2). Parameter names are free-form text, but are dictated by the data provider's expected input. An asterisk (*) appears next to mandatory parameters, and each parameter's corresponding value can be specified as either XPath 1.0 or XQuery 1.0. In addition to the functions provided by the XPath 1.0 or XQuery 1.0 standards, OSM provides a custom function, instance(string) that allows the output of one data provider to be used as the input of another. The parameters required by each of the built-in data providers is documented in the sections that follow.

Figure 7-2 Data Provider Interface Tab

For instructions on how to define these data providers in Studio, including field-level detail, see the Design Studio Help.

Accessing Data through Data Providers

To use a Data Provider, you include a data element in the order template, define a behavior for it and use an XPath expression to access the Data Provider and extract the data that you wish to display in the data element.

For example, the following XPath illustrates how to call a web service provider instance named "DataInstance" and return the value of the "my_element" view data element.

instance('DataInstance')/Data/_root/my_element

For XQuery, you would use vf:instance().

Augmenting or Overriding Data

In most cases, a data provider references order data from an external source, another behavior, or as static values defined within the data provider. In addition to these options, you can also add explicit parameter values from within an XQuery or XPath that augment or override the parameters defined in the OSM data dictionary.

For example, the following variable can be declared with parameters that have not been defined within the OSM data dictionary from within an XQuery:

declare variable $dataInstanceParams := 
    <params>
        <oms:url>file://users/bdueck/catalog.xml</oms:url>
        <fooParam>barValue</fooParam>
    </params>;

You can call a data instance function using a sequence of parameters declared in the variable above. For example:

log:info($log,local-name(vf:instance($order/oms:GetOrder.Response/oms:_root/oms:data[1],'DataInstance',$dataInstanceParams/*)/*[]))

You can call a data instance function using parameters passed as parameters on the function one by one. For example:

log:info($log,local-name(vf:instance($order/oms:GetOrder.Response/oms:_root/oms:data[1],'DataInstance',<oms:url>file://us/catalog.xml</oms:url>)/*[1])),

You can call a data instance function using parameters passed as parameters on the function one by one and include two parameters. For example:

log:info($log, local-name(vf:instance($order/oms:GetOrder.Response/oms:_root/oms:data[1],'DataInstance',<oms:url>file://us/catalog.xml</oms:url>,<foo>bar</foo>)/*[1]))

Objectel

This adapter provides a reliable transport call into Objectel. Although JMS is an asynchronous protocol, the Objectel adapter itself is not. While JMS simplifies transaction management, recovery, offline capabilities, and security, these benefits are not relevant when considered within the context of a behavior. The JMS adapter utilizes additional resources in the application server in the form of temporary JMS destinations to which Objectel sends the response. These can be expensive if an order has many adapters being called concurrently. It is not recommended to use this adapter in this scenario.

Parameters

objectel:extensionName

Description: the name of the Objectel server extension to call.

Mandatory/Optional: Mandatory
objectel:jmsFactory

Description: the name of the JMS factory to be used to access Objectel's JMS queue.

Mandatory/Optional: Optional

Default value - com.oracle.objectel.XMLJMS.QueueConnectionFactory
objectel:queue

Description: The name of the Objectel receive queue.

Mandatory/Optional: Optional

Default value: - com.oracle.objectel.XMLJMS.QueueConnectionFactory
objectel:allowErrorResponse

Description: an optional Boolean parameter name that if specified controls what happens if Objectel returns an error response. If this parameter is set to false (default), an error response from Objectel triggers an exception to be thrown which is in turn displayed as a constraint violation. If this parameter is set to true, the error response is returned by the ObjectelAdapter as a valid instance. This allows another Constraint behavior to apply to that same instance and display an error message accordingly. The benefit of using the default (false) is that you do not have to write an additional behavior to display a default error message. The constraint violation message looks like an exception with a stack trace, but shows the error description returned by Objectel at the top of the message. The benefit of setting this parameter to true is that you have greater control over when the error is shown, at what severity, and what message is displayed.
- false: If this parameter is set to false (the default), an error response from Objectel throws an exception, which is then displayed as a constraint violation. By using false you can avoid writing an additional behavior to display only a default error message. With this method, the constraint violation message looks like an exception with a stack trace, but shows the error description returned by Objectel at the top of the message.
- true: If this parameter is set to true, the error response is returned by the ObjectelAdapter as a valid instance. This allows another Constraint behavior to apply to that same instance and display an error message accordingly. By setting the parameter to true, you have greater control over:
  - When the error should be shown
  - The severity level displayed
  - The exact error message to display.
- All other parameters are passed directly as name/value pairs to the server extension.

Order

This adapter lets you use order data from any OSM order as an external instance. This is useful for using related order data from other orders within OSM.

Parameters

oms:OrderID

Description: The order ID of the order to be retrieved.

Mandatory/Optional: Mandatory
oms:View

Description: The view to use when retrieving order data.

Mandatory/Optional: This is required if the OMS:OrderHistID is not supplied.
oms:OrderHistID

Description: The order history ID to use when retrieving order data.

Mandatory/Optional: This is required if OMS:View is not supplied.

Adding a New Order Data Provider

To add a new Data Provider which uses the Order adapter:

In Design Studio, add a new Data Provider. From the Studio menu, select New, then select Order and Service Management, and then select Data Provider.
In the Data Provider Wizard, enter a name and folder for the Data Provider and set Provider Type to Order.

The new Order Data Provider is added to the Design Studio project.
Edit the Data Provider.
In the Data Provider editor, on the Input Parameters section of the Interfaces tab, specify values for either the oms:View or oms:orderHistID parameters.
Set the Default Value to either XQuery or XPath and enter your request code in the Default Value edit box.
Optionally specify the XML structure of the data in the Results Document edit box.

The definition of GetOrderResponse is located in the order management web service schema at osm_home\SDK\XMLSchema\GetOrder.xsd.

For more information, see the discussion on Data Providers in the Design Studio Help. Also, see "Accessing Data through Data Providers."

Property File

This adapter retrieves an external Java property file with a given name from the classpath. The format of the XML instance returned by this adapter is specified as:

http://docs.oracle.com/javase/7/docs/api/java/util/Properties.html

Parameters

oms:url

Description: Specifies the file name of the Java property file. The file must be on the classpath and must be in the format of a Java property file.

Mandatory/Optional: Mandatory

SOAP

This adapter lets you access web services from OSM or an external web service server, using the HTTP protocol. You can call SOAP web services from OSM or an external web service server and use the responses within behaviors.

Note:

If you need to configure a proxy server to access the internet, add the following parameters to the OSM WebLogic server startup script:

JAVA_OPTIONS="${JAVA_OPTIONS} -Dhttp.proxyHost=ip_address -Dhttp.proxyPort=port

where ip_address and port are the IP address and port of the proxy server.

For web service calls specific to OSM, use the web service adapter, see "Web Service."

For general web services calls, use the SOAP adapter.

Parameters

soap.endpoint

Description: Specifies the URL to which the SOAP request will be sent.

Mandatory/Optional: Mandatory
soap.action

Description: Contains the URI that identifies the intent of the message.

Mandatory/Optional: Optional
soap.envelope

Description: Specifies the root element of a SOAP message.

Mandatory/Optional: Mandatory, if the soap.body parameter is not defined.
soap.body

Description: Contains the SOAP message intended for the endpoint. If the SOAP body node is not included in the soap.body content, it will be added by the SOAPAdapter.

Mandatory/Optional: Mandatory, if the soap.envelope parameter is not defined.
soap.header

Description: Contains XML data that affects the way the application-specific content is processed by the message provider. If the SOAP header node is not included in the soap.header content, it will be added by the SOAPAdapter.

Mandatory/Optional: Optional
oms:credentials.username

Description: Specifies an authentication user name.

Mandatory/Optional: Optional
oms:credentials.password: An optional authentication parameter

Description: Specifies an authentication password.

Mandatory/Optional: Optional
oms:credentials.scope.host: An optional authentication parameter

Description: Specifies an authentication host parameter.

Mandatory/Optional: Optional
soap.allowErrorResponse:

Description: When set to true, the adapter returns SOAP fault messages to the calling behavior; otherwise, the adapter throws an exception when a SOAP fault response is returned.

Mandatory/Optional: Mandatory

Example of soap.body Parameter

The following is an example of a SOAP body, which would be populated in the soap.body parameter.

<instance name="us-addr" xsi:type="externalInstanceType">
<adapter>com.mslv.oms.view.rule.adapter.SOAPAdapter</adapter>
<parameter name="soap.endpoint">'http://ws2.serviceobjects.net/av/AddressValidate.asmx'</parameter>
<parameter name="soap.body" xsi:type="xqueryType">
<soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<sa:ValidateAddress xmlns:sa="http://www.serviceobjects.com/">
<sa:Address xsi:type="soapenc:string">{ ../street/text() }</sa:Address>
<sa:City xsi:type="soapenc:string">{ ../city/text() }</sa:City>
<sa:State xsi:type="soapenc:string">{ ../state/text() }</sa:State>
<sa:PostalCode xsi:type="soapenc:string"/>
<sa:LicenseKey xsi:type="soapenc:string">{ ../soap_license_key/text() }</sa:LicenseKey>
</sa:ValidateAddress>
</soap:Body>
</parameter>
</parameter name="soap.action">'http://www.serviceobjects.com/ValidateAddress'</parameter>
<cache>
<scope>NODE</scope>
</cache>
</instance>

Example of soap.envelope Parameter

The following is an example of a SOAP envelope, which would be populated in the soap.envelope parameter.

<?xml version="1.0" encoding="UTF-8"?>
<com:modelEntity xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:adapt="http://xmlns.oracle.com/communications/sce/osm/model/adapter" xmlns="http://xmlns.oracle.com/communications/sce/osm/model/adapter" xmlns:com="http://www.mslv.com/studio/core/model/common" xmlns:prov="http://xmlns.oracle.com/communications/sce/osm/model/provisioning" xsi:type="adapt:adapterType" name="Send_Order">
  <com:displayName>Send_Order</com:displayName>
  <com:saveVersion>49</com:saveVersion>
  <com:interface>
    <com:inputParameter xsi:type="adapt:xpathInputParameterType" name="soap.endpoint"><adapt:contentType>XPATH</adapt:contentType><adapt:defaultValue>'http://localhost:7001/osm/wsapi'</adapt:defaultValue></com:inputParameter>
    <com:inputParameter xsi:type="adapt:xpathInputParameterType" name="soap.envelope"><adapt:contentType>XQUERY</adapt:contentType><adapt:defaultValue>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:osm="http://xmlns.oracle.com/communications/ordermanagement">
  <soapenv:Header>
      <wsse:Security soapenv:mustUnderstand="1" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <wsse:UsernameToken wsu:Id="UsernameToken-10570647">
            <wsse:Username>osm</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">administrator</wsse:Password>
         </wsse:UsernameToken>
      </wsse:Security>
   </soapenv:Header>
   <soapenv:Body>
      <osm:CreateOrderBySpecification xmlns:osm="http://xmlns.oracle.com/communications/ordermanagement" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
         <osm:Specification>
            <osm:Cartridge>
               <osm:Name>LGT_PSTN_Corp</osm:Name>
               <osm:Version>1.0.0</osm:Version>
            </osm:Cartridge>
            <osm:Type>LGT_PSTN_CorpOrder</osm:Type>
            <osm:Source>LGT_PSTN_CorpOrder</osm:Source>
          </osm:Specification>
         <osm:Reference>Create by WebService</osm:Reference>
         <osm:Priority>5</osm:Priority>
         <osm:AutoAddMandatoryData>true</osm:AutoAddMandatoryData>
         <osm:StartOrder>true</osm:StartOrder>
         <osm:Data>
            <_root>
                    <Customer_info>
                         <Customer_name> hongbin </Customer_name>
                        <Customer_Address>shangwen</Customer_Address>
                        <Customer_region>1</Customer_region>
                        <Customer_contact>1391-322-323</Customer_contact>
                   </Customer_info>
                    <Order_info>
                         <Order_Id> 1000006</Order_Id>
                        <Order_version>1 </Order_version>
                   </Order_info>
                    <Service_info>
                         <Service_Type>1</Service_Type>
                        <Corp_TelephoneNumber>900893322 </Corp_TelephoneNumber>
                   </Service_info>
            </_root>
         </osm:Data>
      </osm:CreateOrderBySpecification>
   </soapenv:Body>
</soapenv:Envelope></adapt:defaultValue></com:inputParameter>
    <com:inputParameter xsi:type="adapt:xpathInputParameterType" name="oms:credentials.username"><adapt:contentType>XPATH</adapt:contentType><adapt:defaultValue>'osm'</adapt:defaultValue></com:inputParameter>
    <com:inputParameter xsi:type="adapt:xpathInputParameterType" name="oms:credentials.password"><adapt:contentType>XPATH</adapt:contentType><adapt:defaultValue>'administrator'</adapt:defaultValue></com:inputParameter>
  </com:interface>
  <com:implementation xsi:type="adapt:adapterImplementationType">
    <adapt:builtInType>SOAP</adapt:builtInType>
  </com:implementation>
  <adapt:cache enabled="true">
    <adapt:scope>SYSTEM</adapt:scope>
    <adapt:timeout>15000</adapt:timeout>
    <adapt:maxsize>50</adapt:maxsize>
  </adapt:cache>
</com:modelEntity>

XML Attachment

This adapter lets you use an attachment from any OSM order as an external instance. It is useful for using related-order-data from other orders within OSM.

Parameters

oms:OrderID

Description: The order ID of the order to be retrieved.

Mandatory/Optional: Mandatory
oms:FileName

Description: The name of the attachment to use when retrieving the order data.

Mandatory/Optional: Mandatory

XML File

This adapter lets you use an XML file accessible from any URL as an external instance. It is useful for integrating external XML data located in a file system, FTP site, from HTTP, or in a Java JAR file.

Parameters

oms:url

Description: The URL of the file to retrieve.

Mandatory/Optional: Mandatory

XML Validation

This adapter validates a provided XML instance document according to a user-defined schema. The document may be provided either as a URL or as an element. The schema may also be provided as a URL or as an element. The returned document conforms to the element specified by http://xmlns.oracle.com/communications/ordermanagement#ValidationResult.

Parameters

document

Description: The file name of the XML document to validate.

Mandatory/Optional: Mandatory
schema

Description: The file name of the XSD used to perform the XML validation.

Mandatory/Optional: Mandatory

JDBC

This adapter lets OSM query any JDBC database, then use the results within a behavior. This adapter is particularly useful for acquiring information stored in an external database.

Parameters

oms:dataSource

Description: The JNDI name of the data source providing the database connection information. For example <code>'mslv/oms/oms1/internal/jdbc/DataSource'. The data source must be defined through the WebLogic server console.

Mandatory/Optional: Mandatory
oms:sql

Description: The SQL that is sent to the database. To run a SQL stored procedure, this parameter must comply with the format specified by:

http://docs.oracle.com/javase/7/docs/api/java/sql/CallableStatement.html

Mandatory/Optional: Mandatory
in:1 . . . in:n

Description: 1 to n additional optional input parameters may be supplied that are bound to parameters defined in the oms:sql value.

Mandatory/Optional: Optional
out:1 . . . out:n

Description: 1 to n additional optional output parameters that are used when calling SQL stored procedures that have output parameters defined. The parameter value specifies the SQL type name of the parameter, and must be defined at:

http://docs.oracle.com/javase/7/docs/api/java/sql/Types.html

Mandatory/Optional: Optional

Web Service

This external instance adapter lets you invoke the GetOrder and FindOrder OSM Web Service operations. The adapter acts as a wrapper around OSM's Web Services API for these two web services, allowing these operations to be called from external instances.

For other web service calls, use the SOAP adapter. See "SOAP."

Parameters

soap.request

Description: Set this parameter to one of the following:
- The contents of what would normally be in the Body element of the web service request. For example, ord:GetOrder or ord:FindOrder.
- A soap:Envelope element, that is, the entire soap request.
- A soap:Body element, that is, the body element of the soap request.
Mandatory/Optional: Mandatory

See "GetOrder" and "FindOrder" for more information on these web service transactions.

Adding a New Web Service Data Provider

To add a new Data Provider which uses the Web Service adapter:

In Design Studio, add a new Data Provider. From the Studio menu, select New, then select Order and Service Management, and then select Data Provider.
In the Data Provider Wizard, enter a name and folder for the Data Provider and set Provider Type to Web Service.

The new Web Service Data Provider is added to the Design Studio project.
Edit the Data Provider.
In the Data Provider editor, on the Input Parameters section of the Interfaces tab, select the soap.request* parameter.
Set the Default Value to XQuery and enter the request XQuery code in the Default Value edit box. See "Sample soap.request XQuery" for an example.

You can optionally specify the request as an XPath instance instead by setting the Default Value to XPath and entering the request XPath code in the Default Value edit box.
Optionally specify the XML structure of the data in the Results Document edit box.

Definitions of FindOrderResponse and GetOrderResponse declarations are located in the order management web service schema at osm_home\SDK\WebService\wsdl\OrderManagementWS.xsd.

For more information, see the discussion on Data Providers in the Design Studio Help.

Sample soap.request XQuery

The following is a soap.request XQuery example for a web services Data Provider. You can also specify the input as a SOAP envelope or a SOAP Body.

<ord:GetOrder xmlns:ord="http://xmlns.oracle.com/communications/ordermanagement">
   <ord:OrderId>1</ord:OrderId>
   <ord:View>review_details_view</ord:View>
   <ord:AmendmentFilter>
   <ord:LevelOfDetail>AmendmentsSummary</ord:LevelOfDetail>
   </ord:AmendmentFilter>
   <ord:LifecycleEventFilter>
   <ord:RetrieveLifecycleEvents>true</ord:RetrieveLifecycleEvents>
   </ord:LifecycleEventFilter>
</ord:GetOrder>

Accessing Data

To use the Data Provider, include a data element in the order template, define a behavior for it, and use an XPath expression to access the Data Provider and extract the data to display in the data element. See "Accessing Data through Data Providers."

Whenever the Web Service adapter is called through a Data Provider, GetOrderRequest is executed and a response returned. If logging is set to debug for the OrderAdapter, a message similar to the one below is displayed on the WebLogic Administration console:

<09-Feb-2012 2:57:57,884 IST PM> <DEBUG> <adapter.OsmWebServiceAdapter> <ExecuteThread: '10' for queue: 'oms.web'> <<GetOrderResponse xmlns="http://xmlns.oracle.com/communications/ordermanagement">
    <OrderSummary>
        <Id>16</Id>
        <Specification>
            <Cartridge>
                <Name>view_framework_demo</Name>
                <Version>1.0.0.0.0</Version>
            </Cartridge>
            <Type>vf_demo_web</Type>
            <Source>vf_demo_web</Source>
        </Specification>
        <State>open.running.in_progress</State>
        <Reference>N1</Reference>
        <CreatedDate>2012-02-08T17:55:31.000+05:30</CreatedDate>
        <ExpectedDuration>P1D</ExpectedDuration>
<ExpectedOrderCompletionDate>2012-02-09T17:55:37.000+05:30</ExpectedOrderCompletionDate>
        <ProcessStatus>n/a</ProcessStatus>
        <Priority>5</Priority>
    </OrderSummary>
    <Data>
        <osmc:_root
            xmlns:osmc="urn:oracle:names:ordermanagement:cartridge:view_framework_demo:1.0.0.0.0:view:enter_account_information" index="0">
            <osmc:account_information index="1328703937231">
                <osmc:first_name index="1328703937242">name</osmc:first_name>
                <osmc:last_name index="1328703937243">lastname</osmc:last_name>
                <osmc:country index="1328703937244">US</osmc:country>
                <osmc:address_information index="1328703937233">
                    <osmc:address_details_us index="1328703937236">
                        <osmc:validate_address_via_soap index="1328703937238">No</osmc:validate_address_via_soap>
                        <osmc:street index="1328703937239">street</osmc:street>
                        <osmc:city index="1328703937241">city</osmc:city>
                        <osmc:state index="1328703937240">MI</osmc:state>
                        <osmc:zip_code index="1328703937237">12323</osmc:zip_code>
                    </osmc:address_details_us>
                    <osmc:address_details_ca index="1328703937234">
                        <osmc:validate_address_via_soap index="1328703937235">No</osmc:validate_address_via_soap>
                    </osmc:address_details_ca>
                </osmc:address_information>
            </osmc:account_information>
            <osmc:info_roopa index="1328703937245">nikhil</osmc:info_roopa>
        </osmc:_root>
    </Data>
</GetOrderResponse

Custom Data Providers

In addition to the built-in data providers described in previous sections, Design Studio supports custom data providers. You can develop a custom data provider class in a project in Design Studio as part of a solution. This provider class must implement the com.mslv.oms.view.rule.ExternalInstanceAdapter interface. This interface is documented in the Javadoc distribution found in the OSM SDK.

The implementation class can be made available to the OSM run time system in two ways:

Package the class into an Java archive (jar file) with an arbitrary name and place the jar file in the resources directory of the Studio project(s) that define Behaviors referencing the data provider. The class will be available as soon as the project is deployed
Add the compiled adapter class to the customization.jar file in the oms.ear file. The class will be available as soon as the OSM application is redeployed. See "Working with the oms.ear File" for information about unpacking, packing, and redeploying the oms.ear file.

The ExternalInstanceAdapter.retrieveInstance(ViewRuleContext, Map) method provides a Map of name/value pairs of arguments defined in the data provider's Design Studio definition and their corresponding values for an invocation of an instance of this class. The com.mslv.oms.view.rule.adapter.AbstractAdapter class provides a number of methods to assist in extracting properly type cast parameter values from that Map. AbstractAdapter is included in the automation_plugins.jar archive found in the osmLib directory of a Design Studio OSM project, as well as in the automation/automationdeploy_bin subdirectory of an OSM SDK installation.

Handling Parameters

Custom data providers, like built-in providers, support input parameters. The following examples illustrate how to access those parameters.

Example 1 (incorrect usage)

String stringParamValue = (String) parameters.get(MY_STRING_PARAM); The value returned by parameters.get(...) may not be a String, resulting in a ClassCastException.

Example 2 (incorrect usage)

String stringParamValue = parameters.get(MY_STRING_PARAM).toString(); The parameters.get() call may return a null value resulting in a null pointer exception. Also, the value returned may be an XML DOM fragment, requiring a more sophisticated mechanism for value extraction than simply calling toString().

Example 3 (correct usage)

String stringParamValue = = getStringParam(parameters, MY_STRING_PARAM); The getStringParam(Map, String) call automatically performs the appropriate conversion to coerce a parameter value into a String. This method is intended for extracting a required parameter value. If a value for MY_STRING_PARAM was not provided, or if the value cannot be coerced into a String, a BadParameterException is thrown. To retrieve optional parameter values, use getStringParam(Map, String, String) instead; see Example 4.

Example 4 (correct usage)

String stringParamValue = getStringParam(parameters, MY_STRING_PARAM, "a default value"); The MY_STRING_PARAM parameter is retrieved as an optional parameter. If a value for MY_STRING_PARAM is provided, it is returned, otherwise, "a default value" is returned.The AbstractAdapter class also provides similar methods to extract boolean, numeric, and XML DOM Node parameter values:

boolean booleanParamValue = getBooleanParam(parameters, MY_BOOLEAN_PARAM);
int intParamValue = getIntParam(parameters, MY_NUMBER_PARAM);
Node nodeParamValue = getNodeParam(parameters, MY_NODE_PARAM);

The following code snippet illustrates a simple custom data provider class:

/*
 * Copyright © 1998, 2012, Oracle and/or its affiliates. All rights reserved.
*/
package oracle.communications.ordermanagement.example;
 
import java.util.Map;
 
import oracle.communications.ordermanagement.util.xml.XMLHelper;
 
import org.w3c.dom.Document;
import org.w3c.dom.Element;
 
import com.mslv.oms.view.rule.ExternalInstanceAdapter;
import com.mslv.oms.view.rule.ViewRuleContext;
import com.mslv.oms.view.rule.adapter.AbstractAdapter;
 
/**
 * <p>
 * This class exemplifies a custom Data Provider. In particular, it demonstrates a provider that returns the familiar "Hello World!"
 * example. The data returned by this provider can in turn be used as input to any Behavior type.
 * </p>
 * <p>
 * Like all data providers, this class implements the {@link ExternalInstanceAdapter} interface. This interface defines a single method,
 * {@link ExternalInstanceAdapter#retrieveInstance(ViewRuleContext, Map) retrieveInstance(ViewRuleContext, Map)}. The
 * {@link ViewRuleContext} argument provides various context hooks to this Data Provider implementation instance. The <code>Map</code>
 * argument contains the name/value pairs of arguments defined in the Data Provider's Studio definition and their corresponding values for
 * the current invocation of this Data Provider implementation instance. It additionally extends the {@link AbstractAdapter} class.
 * <code>AbstractAdapter</code> provides a number of utility methods for retrieving properly type-cast parameters from the parameter
 * <code>Map</code>.
 * </p>
 * 
 * @author Copyright © 1998, 2012, Oracle and/or its affiliates. All rights reserved.
 * 
 */
public final class ExampleProvider extends AbstractAdapter implements ExternalInstanceAdapter {
 
    /**
     * The name of a parameter that specifies the salutation to return from {@link #retrieveInstance(ViewRuleContext, Map)}. For example, if
     * a value of <code>Goodbye</code> is specified, the message <code>Goodbye World!</code> will be returned. This example does not require
     * this parameter to exist. If it does not, the message <code>Hello World!</code> will be returned.
     */
    public static final String SALUTATION_PARAM_NAME = "salutation";
 
    private static final String DEFAULT_SALUTATION = "Hello";
 
    /**
     * <p>
     * This implementation simply returns the root {@link Element} of a {@link Document} containing the <code>String "Hello World!"</code>
     * in the contents, i.e., the root of the XML:
     * 
     * <pre>
     * &lt;response&gt;
     *     &lt;message&gt;Hello World!&lt;/message&gt;
     * &lt;/response&gt;
     * </pre>
     * 
     * </p>
     * <p>
     * The <code>instance('<var>name</var>')</code> Behavior function resolves to the document root element returned by this method.
     * Therefore, the syntax for locating this provider's message (assuming the Data Provider associated with this class is named
     * <code>ExampleProvider</code>) is <code>instance('ExampleProvider')/message</code>.
     * </p>
     * 
     * @param ctx
     *            provides various context-specific hooks for use by this instance
     * @param params
     *            <code>Map</code> of name/value pairs, where the key is the parameter name defined in the Data Provider definition that is
     *            associated with this class, and the value is the resolved value of that parameter for a specific invocation of this
     *            method. This example does not expect or require any parameters.
     * @return the root <code>Document Element</code>
     */
    @Override
    public Element retrieveInstance(final ViewRuleContext ctx, final Map<String, Object> params) throws Exception {
        /*
         * This demonstrates how to use the utility methods inherited from AbstractAdapter to return a parameter value, though here the
         * "salutation" parameter is not expected to exist.
         */
        final String salutation = getStringParam(params, SALUTATION_PARAM_NAME, DEFAULT_SALUTATION);
 
        /*
         * Create the response. An actual provider implementation would likely calculate or retrieve the response from an external system.
         */
        final String response = "<response><message>" + salutation + " World!</message></response>";
 
        /*
         * The code invoking this method expects a org.w3c.dom.Document root org.w3c.dom.Element. The XMLHelper utility class provides a
         * number of DOM manipulation methods, including various String parsers.
         */
        final Document responseDoc = XMLHelper.parseText(response, false);
        return responseDoc.getDocumentElement();
    }
}