8 Using Web Services

8.1 Introduction to Using Web Services in MAF Applications

Web services allow applications and their features to exchange data and information through defined application programming interfaces. Using web services you can expose business functionality irrespective of the platform or language of the originating application because the business functionality is exposed in such a way that it is abstracted to a message composed of standard XML constructs that can be recognized and used by other applications.

Some of the most typical reasons for using web services in MAF applications are:

• To add functionality that is readily available as a web service, but which would be time-consuming to develop within the application.

• To provide access to an application that runs on a different architecture.

MAF supports SOAP web services and allows you to integrate a third-party web service into your MAF AMX application feature.

Using web services in your MAF application enables you to do the following:

• Provide either all of the data or a subset of data from a larger (enterprise) data store in which the end user of the mobile application is interested.

• Provide functionality that is too computationally intensive for the mobile device's resources. This could be due to either the actual amount of work the device would need to perform, or the fact that the functionality is based on a much larger data set than the one that is locally available on the device.

The following web service scenarios usage demonstrate the data access (scenario 1) as well as computational and data-driven functionality (scenarios 2 and 3):

• Fetch a set of Opportunity data from the enterprise data store to enable the end user to manipulate it on the device, and then post changes back to the enterprise data store through the web service.

• Request a report be generated on some enterprise data, and then fetch the report.

• Obtain a map image of a route to a customer site.

8.2 Creating Web Service Data Controls

The most common way of using web services in an application feature developed with MAF is to create a data control for an external web service. For more information, see Section 7.1, "Introduction to Bindings and Data Controls."

8.2.2 What You May Need to Know About Web Service Data Controls

After the web service data control has been created, the web service operations and return values of the operations are displayed in the Data Controls window, illustrated in Figure 8-2.

Figure 8-2 Web Service Data Control

You can edit web service data controls by clicking Edit data control, as shown in Figure 8-3.

Like other data controls, you can drag and drop the objects returned by the web service operations to create user interface components in a MAF AMX page. For more information, see Section 5.3.2.3, "Adding Data Controls to the View." When data returned from a web service operation is displayed, the following object types are handled:

• Collections

• Complex objects returned by a web service operation

• Nested complex objects returned by a web service operation

Using a web service operation, both standard and complex data types can be updated and deleted.

As illustrated by Figure 8-2, each data control object is represented by an icon. Table 8-1 describes what each icon represents, where it appears in the Data Controls Palette hierarchy, and what components it can be used to create. For more information see Section 7.6, "Creating Databound UI Components from the Data Controls Palette."

Table 8-1 Data Controls Palette Icons and Object Hierarchy for Web Services

Icon	Name	Description	Used to Create...
	Data Control	Represents a data control. You cannot use the data control itself to create UI components, but you can use any of the child objects listed under it. Typically, there is one data control for each web service.	Serves as a container for other objects and is not used to create anything.
	Collection	Represents a data collection returned by an operation on the service. Collections also appear as children under method returns, other collections, or structured attributes. The children under a collection may be attributes, other collections, custom methods, and built-in operations that can be performed on the collection.	Forms, tables, graphs, trees, range navigation components, and master-detail components. See also Section 6.5, "Providing Data Visualization."
	Attribute	Represents a discrete data element in an object (for example, an attribute in a row). Attributes appear as children under the collections or method returns to which they belong.	Label, text field, date, list of values, and selection list components. See also Section 6.2, "Designing the Page Layout."
	Structured Attribute	Represents a returned object that is a complex type but not a collection. For example, a structured attribute might represent a single user assigned to the current service request.	Label, text field, date, list of values, and selection list components. See also Section 6.2, "Designing the Page Layout."
	Method	Represents an operation in the data control or one of its exposed structures that may accept parameters, perform some business logic and optionally return single value, a structure or a collection of those.	Command components. For methods that accept parameters: command components and parameterized forms. See also Section 6.3, "Creating and Using UI Components."
	Method Return	Represents an object that is returned by a web service method. The returned object can be a single value or a collection. A method return appears as a child under the method that returns it. The objects that appear as children under a method return can be attributes of the collection, other methods that perform actions related to the parent collection, and operations that can be performed on the parent collection. When a single-value method return is dropped, the method is not invoked automatically by the framework. You should either drop the corresponding method as a button to invoke the method, or if working with task flows you can create a method activity for it.	The same components as for collections and attributes and for query forms.
	Operation	Represents a built-in data control operation that performs actions on the parent object. Data control operations are located in an Operations node under collections. If an operation requires one or more parameters, they are listed in a Parameters node under the operation. The following operations for navigation and setting the current row are supported: First, Last, Next, Previous, setCurrentRowWithKey, and SetCurrentRowWithKeyValue. Execute is supported for refreshing queries. Create and Delete are available as applicable, depending on the web service operation. Because the web service data controls are not transactional, Commit and Rollback are not supported.	User interface command components, such as buttons, links, and menus. For more information, see Section 6.3, "Creating and Using UI Components."
	Parameter	Represents a parameter value that is declared by the method or operation under which it appears. Parameters appear in the Parameters node under a method or operation. Array and structured parameters are exposed as updatable structured attributes and collections under the data control, which can be dropped as an ADF form or an updatable table on the UI. You can use the UI to build a parameter that is an array or a complex object (not a standard Java type).	Label, text, and selection list components. For more information, see Section 6.3.15, "How to Use List View and List Item Components."

package provider.ebs.soap; 

import oracle.adfinternal.model.adapter.webservice.provider.soap.SOAPProvider;
import oracle.adfinternal.model.adapter.webservice.provider.soap.SoapHeader;

public class EBSSOAPProvider extends SOAPProvider {

public SoapHeader[] getAdditionalSoapHeaders() {
   SoapHeader header[] = new SoapHeader[2]; 
   SoapHeader token = null; 
   SoapHeader user = null; 
   SoapHeader pass = null; 

   header[0] = new SoapHeader("http://xmlns.oracle.com/apps/fnd/soaprovider/plsql/fnd_user_pkg/",
                              "SOAHeader"); 
   header[0].addChild(new SoapHeader(
                              "http://xmlns.oracle.com/apps/fnd/soaprovider/plsql/fnd_user_pkg/",
                              "Responsibility",
                              "SYSTEM_ADMINISTRATOR"));
   header[0].addChild(new SoapHeader(
                              "http://xmlns.oracle.com/apps/fnd/soaprovider/plsql/fnd_user_pkg/",
                              "RespApplication",
                              "SYSADMIN")); 
   header[0].addChild(new SoapHeader(
                              "http://xmlns.oracle.com/apps/fnd/soaprovider/plsql/fnd_user_pkg/",
                              "SecurityGroup",
                              "STANDARD"));
   header[0].addChild(new SoapHeader(
                              "http://xmlns.oracle.com/apps/fnd/soaprovider/plsql/fnd_user_pkg/",
                              "NLSLanguage", 
                              "AMERICAN")); 
   header[0].addChild(new SoapHeader(
                              "http://xmlns.oracle.com/apps/fnd/soaprovider/plsql/fnd_user_pkg/",
                              "Org_Id", 
                              "0"));

   header[1] = new SoapHeader(
               "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd",
               "Security");
   token = new SoapHeader(
              "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd",
              "UsernameToken");
   user = new SoapHeader(
              "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd",
              "Username",
              "sysadmin");
   pass = new SoapHeader(
              "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd",
              "Password",
              "sysadmin");

   header[1].addChild(token);
   token.addChild(user);
   token.addChild(pass); 

   return header;
   }
}

<soap:Header xmlns:ns1="http://xmlns.oracle.com/apps/fnd/soaprovider/plsql/fnd_user_pkg/">
   <ns1:SOAHeader> 
      <ns1:Responsibility>SYSTEM_ADMINISTRATOR</ns1:Responsibility>
      <ns1:RespApplication>SYSADMIN</ns1:RespApplication>
      <ns1:SecurityGroup>STANDARD</ns1:SecurityGroup>
      <ns1:NLSLanguage>AMERICAN</ns1:NLSLanguage>
      <ns1:Org_Id>0</ns1:Org_Id>
   </ns1:SOAHeader>
   <wsse:Security xmlns:wsse=
      "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
      xmlns="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
      xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" 
      soap:mustUnderstand="1">
      <wsse:UsernameToken xmlns:wsse=
      "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" 
      xmlns="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <wsse:Username>sysadmin</wsse:Username>
         <wsse:Password Type=
          http://docs.oasis-open.org/wss/2004/01/
          oasis-200401-wss-username-token-profile-1.0#PasswordText">sysadmin</wsse:Password>
      </wsse:UsernameToken>
   </wsse:Security>
</soap:Header>

@return

<definition xmlns="http://xmlns.oracle.com/adfm/adapter/webservice"
                   name="SoapService" version="1.0"
                   provider="oracle.adf.model.adapter.webservice.SOAPMessageHandler"
                   wsdl="http://@SRG_WS_HOST@:@SRG_WS_PORT@/SoapService/SoapServicePort?wsdl" >
   <service name="SoapService" namespace="http://model/"
            connection="SoapService"> 
      <port name="SoapServicePort">
         <operation name="echoSoapHeader"/>
      </port> 
   </service>
</definition>

8.3 Creating a New Web Service Connection

The connection information for the web service is stored in the connections.xml file along with the other connections in your application. You do not need to explicitly create this file, as it is generated in the.adf/META-INF directory by the New Web Service Data Control wizard at the time when the web service data control is created (see Section 8.2, "Creating Web Service Data Controls").

You modify the connection settings by editing the connections.xml file.

8.4 Adjusting the Endpoint for a Web Service Data Control

After creating a web service data control, you can modify the endpoint of the URI. This is useful in such cases as when you migrate an application feature from a test to production environment.

You modify the endpoint by editing the connections.xml file.

8.5 Accessing Secure Web Services

MAF supports both secured and unsecured web services. For more information, see Chapter 21, "Securing Mobile Applications."

To access secured web services from your MAF application, you may need to configure web service data controls included in the application.

8.5.1 How to Enable Access to SOAP-Based Web Services

To display the applicable Oracle Web Services Manager policies, be sure to select the port when you create the SOAP Web Service DataControl.

The following predefined security policies are supported for SOAP-based web services:

• oracle/wss_http_token_client_policy

• oracle/wss_http_token_over_ssl_client_policy

• oracle/http_basic_auth_over_ssl_client_policy

• oracle/wss_username_token_client_policy

• oracle/wss_username_token_over_ssl_client_policy

For descriptions of these policies and their usage, see the "Determining Which Predefined Policies to Use" and "Predefined Policies" chapters in Oracle Fusion Middleware Securing Web Services and Managing Policies with Oracle Web Services Manager.

If a SOAP web service is secured, you can access it by configuring the web service data control with either oracle/wss_http_token_over_ssl_client_policy or oracle/wss_http_token_client_policy. To do so, use the Edit Data Control Policies dialog that Figure 8-3 shows. You can open this dialog as follows:

• In the Project Explorer, select the .dcx file located in the application's view controller project.

• In the Structure window, right-click the web service data control that you would like to configure, and then select Define Web Service Security from the context menu.

Figure 8-3 Editing Web Service Data Control Policies

Note:

Oracle Enterprise Pack for Eclipse stores the web service policy definitions in the wsm-assembly.xml file (located in META-INF directory of the application workspace).

<Reference name="URLConnection1"
           className="oracle.adf.model.connection.url.HttpURLConnection"
           adfCredentialStoreKey="MyAuth"
           xmlns="">
   <Factory className="oracle.adf.model.connection.url.URLConnectionFactory"/>
   <RefAddresses>
      <XmlRefAddr addrType="URLConnection1">
         <Contents>
            <urlconnection name="URLConnection1"
                           url="http://myhost.us.example.com:7777/
                                SecureRESTWebService1/Echo">
               <authentication style="challange">
                  <type>basic</type>
                  <realm>myrealm</realm>
               </authentication>
            </urlconnection>
         </Contents>
      </XmlRefAddr>
      <SecureRefAddr addrType="username"/>
      <SecureRefAddr addrType="password"/>
   </RefAddresses>
</Reference>

<Reference name="MyAuthName"
           className="oracle.adf.model.connection.adfmf.LoginConnection"
           adfCredentialStoreKey="MyAuth"
           partial="false"
           manageInOracleEnterpriseManager="true"
           deployable="true"
           xmlns="">
   <Factory className="oracle.adf.model.connection.adfmf.LoginConnectionFactory"/>
   <RefAddresses>
      <XmlRefAddr addrType="adfmfLogin">
         <Contents>
            <login url="http://172.31.255.255:7777/
                        SecuredWeb1-ViewController-context-root/faces/view1.jsf"/>
            <logout url="http://172.31.255.255:7777/
                    /SecuredWeb1-ViewController-context-root/faces/view1.jsf"/>
            <accessControl url="http://myhost.us.example.com:7777/
                           UserObjects/jersey/getUserObjects" />
            <idleTimeout value="10"/>
            <sessionTimeout value="36000"/>
            <userObjectFilter>
               <role name="testuser1_role1"/>
               <role name="testuser2_role1"/>
               <privilege name="testuser1_priv1"/>
               <privilege name="testuser2_priv1"/>
               <privilege name="testuser2_priv2"/>
            </userObjectFilter>
         </Contents>
      </XmlRefAddr>
   </RefAddresses>
</Reference>

8.6 Invoking Web Services From Java

In your MAF application, you can invoke the web services layer from the Java code and use the results in Java methods.

MAF provides the GenericTypeBeanSerializationHandler utility class that you can use to perform conversions between POJOs (JavaBeans objects) and MAF's GenericType objects based on the following set of conversion rules:

1. When converting from POJO to GenericType objects:

   • Standard JavaBeans reflection rules are used for determining properties.

   • Transient properties are ignored in the conversion process.

   • Readable properties are converted into a GenericType attribute.

   • Array properties are represented as repeated attributes in the GenericType.

   • Map properties are represented as individual attributes in the GenericType.

   • Non-primitive properties are represented as nested GenericType objects.

2. When converting from GenericType objects to POJO:

   • Standard JavaBeans reflection rules are used for determining properties.

   • Transient properties are ignored in the conversion process.

   • Writable properties are converted from GenericType attributes.

   • Repeated attributes in the GenericType are converted into an array object.

   • If the POJO implements the Map interface, then any properties that cannot be set through standard accessors are set in the POJO through the set method of the Map.

   • Non-primitive attributes are represented as nested POJO objects.

The advantage of using this helper API is that it allows you to take the response received from a web service and convert it to a JavaBean in a single call.

For example, a web service passes back and forth an Employee object that needs to be reused throughout the business logic. This object has the following set of properties:

• name of type String

• address: a complex object with street, city, state, and zipcode attributes

• id of type long

• salary of type float

• phone of type String, and there could be more than one phone

• password of type String, and the password should never be transmitted to the back-end web service

Example 8-6 shows a potential code for the Employee object.

public class Employee {

   protected String name;
   protected Address address;
   protected long id;
   protected float salary;
   protected String[] phone;
   protected transient String password;

   public String getName() {
      return name; 
   }

   public void setName(String name) {
      this.name = name;  
   }

   public Address getAddress() {
      return address;
   }

   public void setAddress(Address address) {
      this.address = address; 
   }

   public long getId() {
      return id; 
   }

   public void setId(long id) {
      this.id = id;
   }

   public float getSalary() {
      return salary; 
   }

   public void setSalary(float salary) {
      this.salary = salary; 
   }

   public String getPassword() {
      return password;
   }

   public void setPassword(String password) {
      this.password = password;
   }

   public void setPassword(String password) {
      this.password = password; 
   }

   public String[] getPhone() {
      return phone;  
   }

   public void setPhone(String phone) {
      this.phone = phone;  
   }

Example 8-7 shows the potential code for the Address object of the Employee class.

public class Address {

   protected String street;
   protected String city;
   protected String state;
   protected String zipcode;

   public String getStreet() {
      return street; 
   }

   public void setStreet(String street) {
      this.street = street;  
   }

   public String getCity() {
      return city; 
   }

   public void setCity(String city)  {
      this.city = city;  
   }

   public String getState() {
      return state; 
   }

   public void setState(String state) {
      this.state = state;  
   }

   public String getZipcode() {
      return zipcode; 
   }

   public void setZipcode(String zipcode)  {
      this.zipcode = zipcode;  
   }

Keeping in mind the conversion rules, note the following:

1. Since the password is defined as transient, it is ignored with respect to the conversion algorithm.

2. Since name, address, id, and salary all have get and set methods, they will all be converted to and from the GenericType.

3. Based on the property type, properties can be coerced between types, as defined in the coerceToType(Object, Class) method of the oracle.adfmf.misc.Converter class.

4. Complex objects, such as address, are recursed by the conversion algorithm to either build the child GenericType or to create and populate the POJO complex object depending on the direction of the conversion.

5. Since phone is an array of String objects each representing a unique phone number and since the cardinality of this element is greater than one, the conversion algorithm will find all matches of the phone attribute in the GenericType object, present them as an array, and invoke the setPhone method on the bean. The toGenericType method of the GenericTypeBeanSerializationHandler will take each array element and append it to the toGenericType as an individual phone attribute.

With the following defined:

final String EMPLOYEE_VIRTUAL_BEAN_NAME = "EmployeeDC.Types.Employee";
Employee emp = getEmployee();
GenericType gt = null;

• The Employee object is converted to the GenericType as:

  gt = GenericTypeBeanSerializationHelper.toGenericType
                                   (EMPLOYEE_VIRTUAL_BEAN_NAME, emp);
  

• The GenericType is converted to the Employee object as:

  emp = GenericTypeBeanSerializationHelper.fromGenericType
                                    (Employee.class, gt, null);
  

For successful conversion, consider the following:

• Typically, POJOs closely follow their associated GenericType structure.

• When deviating from the GenericType structure, one of the following strategies should be followed:

  1. Additional bean properties should be declared transient.

  2. Optional properties can be excluded from the POJO, provided that the backing service can handle the missing data if used as an operation parameter.

• The GenericType is only exposed in SOAP data controls. The virtual types have an associated virtual bean name that is passed into the toGenericType method. You can access the virtual bean name by hovering over the virtual type in the Data Controls window of Oracle Enterprise Pack for Eclipse. The typical name format is <DCName>.Types.<methodName>.<argName>.

For more information, see Java API Reference for Oracle Mobile Application Framework.

String keyFieldNames[] = {"EMPLID","ACAD_CAREER","INSTITUTION"};
String keyFieldValues[] = {"SR12030","UGRD","PSUNV"};
AmxAccessorIteratorBinding  acIter =
   (AmxAccessorIteratorBinding)((AdfmfJavaUtilities.getValueExpression
                                ("#{bindings.KEYIterator}", Object.class))
                                .getValue(AdfmfJavaUtilities.getAdfELContext()));

BasicIterator iter = acIter.getIterator(); 
GenericType key = (GenericType)iter.getDataProvider();
key.setAttribute("FIELDNAME", keyFieldNames[0]); 
key.setAttribute("FIELDVALUE", keyFieldValues[0]);

int totalRowCount = 0;
int currIndex = 0;

for (int i = 1; i < keyFieldNames.length; i++) {
   totalRowCount = iter.getTotalRowCount();
   currIndex = iter.getCurrentIndex();

   System.out.println("Starting to add rows.. \n\t Total Row Count: " +
                      totalRowCount + "\n\t Current Row Index: " + currIndex);

   // Create rows for key iterator
   iter.createRow();

   totalRowCount = iter.getTotalRowCount();
   System.out.println("\t Total Row Count after creating row: " + totalRowCount);

   if (iter.hasNext()) {
      iter.next();    
   }

   currIndex = iter.getCurrentIndex();
   System.out.println("\t Current Row Index after setting current 
                      index to newly added row: " + currIndex);

   GenericType key1 = (GenericType)iter.getDataProvider();
   key1.setAttribute("FIELDNAME", keyFieldNames[i]);
   key1.setAttribute("FIELDVALUE", keyFieldValues[i]);
}

// Execute method

// Add call to execute the action binding to execute the action. 
// If this is a web service call, the modified GenericType object 
// will be sent to the server and the server will respond appropriately

8.7 Configuring the Browser Proxy Information

If the web service you are to call resides outside your corporate firewall, you need to ensure that you have set the appropriate Java system properties to configure the use of an HTTP proxy server.

By default, MAF determines the proxy information using the system settings on iOS and Android platforms. For example, if the proxy information is set using the Settings utility on an iOS-powered device, then CVM automatically absorbs it.

If you do not want to obtain the proxy information from the device settings, first you need to add the -Dcom.oracle.net.httpProxySource system property. The default value of this property is native, which means that the proxy information is to be obtained from the device settings. You need to disable it by specifying a different value, such as user, for example: -Dcom.oracle.net.httpProxySource=user

CVM uses two different mechanisms for enabling the network connection:

1. The generic connection framework (GCF). If this mechanism is used, the proxy is defined through the system property -Dcom.sun.cdc.io.http.proxy=<host>:<port>

2. java.net API. If this mechanism is used, the proxy is defined through the standard http.proxyHost and http.proxyPort.

In either case, it is recommended to define all three properties in the cvm.properties file, which would look similar to the following:

java.commandline.argument=-Dcom.oracle.net.httpProxySource=user
java.commandline.argument=-Dcom.sun.cdc.io.http.proxy=www-proxy.us.mycompany.com:80
java.commandline.argument=-Dhttp.proxyHost=www-proxy.us.mycompany.com
java.commandline.argument=-Dhttp.proxyPort=80