15 Exposing URL Services Using the ADF Model Layer

This chapter explains how to expose URL services using the ADF Model layer and how the URL service appears in the Data Controls panel that you can use to design a databound user interface.

This chapter includes the following sections:

Section 15.1, "About Using ADF Model with URL Services"
Section 15.2, "Exposing URL Services with ADF Data Controls"
Section 15.3, "Using URL Service Data Controls"

15.1 About Using ADF Model with URL Services

A URL service can be simply a URL against which a query is posted, so that the URL can be exposed as an ADF form. For example, say you have a URL service that allows you to access employee data for your company. This data can be retrieved using a URL as shown in Example 15-1.

Example 15-1 Sample URL that Accesses a URL Service

http://example.com/getEmployee?empId=20+deptId=10

This simple URL that accesses employee data can become an ADF data control with a method (getEmployee) and two parameters (empId and deptId), that can then be dropped on a page as a form.

URL services can also utilize representational state transfer (REST) actions. REST services are web services that can be accessed using a simple HTTP URL, rather than a more complex SOAP protocol. The HTTP actions (GET, PUT, POST, DELETE) are mapped to service operations that access and manipulate data at the service implementation. The response data can be returned in delimiter separated value and XML formats, and you can specify an XSD URL to define the input format for the PUT and POST actions.

15.1.1 URL Services Use Cases and Examples

The REST architecture simplifies web service invocation by representing a web service as an HTTP resource, so that web service methods and operations look like a resources on the server that can be accessed through an HTTP URL.

For example, say a web service has a method called getEmployee(int EmpID). Using the REST architecture, this can become http://mywebservice.com/myService/getEmployee?EmpID=20. When represented as a plain HTTP URL, it is easy to use the URL service data control to quickly create a databound page that accesses this service.

15.1.2 Additional Functionality for URL Services

You may find it helpful to understand other data access features before you start working with URL services. Following are links to other functionality that may be of interest.

You can design a databound user interface by dragging an item from the Data Controls panel and dropping it on a page as a specific UI component. For more information, see Section 13.4.1, "How to Use the Data Controls Panel."
For information about creating data controls for application modules, see Chapter 13, "Using ADF Model in a Fusion Web Application."
For information about creating web service data controls, see Chapter 14, "Exposing Web Services Using the ADF Model Layer."
For information about other types of data controls, see Appendix H, "Data Controls in Fusion Web Applications."

15.2 Exposing URL Services with ADF Data Controls

The URL service data control enables you to access and consume data streams from specified URLs. A URL service data control can represent multiple operations. For example, the GET operation and the PUT operation for a given URL service can be represented by the same data control.

15.2.1 How to Create a URL Connection

You use the Create URL Connection dialog to create a URL connection by supplying a name and the connection details required to access a URL endpoint.

Before you begin:

It may be helpful to have an understanding of how URL service data controls are used in ADF applications. For more information, see Section 15.1, "About Using ADF Model with URL Services."

You may also find it helpful to understand additional functionality that can be added using other URL services features. For more information, see Section 15.1.2, "Additional Functionality for URL Services."

You must have access to the URL service that the data control will access, and launch JDeveloper.

To create a URL connection:

From the main menu, choose File > New.
In the New Gallery, expand General, select Connections and then URL Connection, and click OK.
In the Create URL Connection dialog, select where to create the connection.

Select Application Resources if you want the URL connection to be available only within the application. Select Resource Palette if you want the URL connection to be available from the Resource Palette for use in other applications.
Enter a name for the connection.
In the URL Endpoint field, enter the URL of the desired data stream.

Typically, this includes just the host and port. Do not include any URL parameters (or example, http://service.example.com:7101/)
Select the level of authentication from the Authentication Type dropdown.

None is the default authentication type and disables authentication. Use Digest when security is desired. In this way, the password will be transmitted across the network as an MD5 digest of the user's password and cannot be determined by sniffing network traffic. Basic authentication is primarily only useful when service access over the network does not require high security.
If digest or basic authentication is selected, specify the user name and password required to access the web site.
If the URL is associated with a protected area of the overall web site, enter the authentication realm.
After you have entered the name and endpoint, you can click Test Connection to verify URL connection is valid.
Click OK to create the connection.

15.2.2 How to Create a URL Service Data Control

You can create a URL Service data control using the Create URL Service Data Control wizard, which is available from the New Gallery. When you create URL service data controls, you use the wizard to create each operation, one at a time.

Before you begin:

It may be helpful to have an understanding of how URL service data controls are used in ADF applications. For more information, see Section 15.1, "About Using ADF Model with URL Services."

You must have access to the URL service that the data control will access.

You should have already created the URL connection you will use, as described in Section 15.2.1, "How to Create a URL Connection."

You must launch JDeveloper, and open the application to which you want to add the URL service data control.

To create a URL service data control:

In the Application Navigator, right-click the data model project and choose New.
In the New Gallery, expand Business Tier, select Data Controls and then URL Service Data Control, and click OK.

Note:

If you don't see the URL Service Data Control item in the New Gallery, click the All Features tab.
In the Create URL Service Data Control wizard (on the Data Source page), provide a name for the data control.

Because each data control represents a single operation for the URL service, the name should reflect both the service and the operation. For example, you might name the data control for the GET operation of the EmployeeData URL service emp_get.
Select the URL connection for the data control to use.
- If you have not yet created a URL connection, select Create New Connection from the Connection dropdown. You will specify the connection details and the action (HTTP method) for this data control on the connection page.
- If you have already created a URL connection, select the connection you want to use from the Connection dropdown.
From the HTP Method dropdown list, select the action for this data control.
Optionally, select the Include HTTP Header Parameter checkbox. For more information, see Section 15.2.4, "How to Include a Custom Header Parameter for a URL Service Data Control."
Enter the source for the URL service (for example, servicepath/servicename), and click Next.

If this operation requires a parameter, you can use the format ?symbol=##ParamName## to specify it (for example, servicepath/servicename?symbol=##id##). You can also use a parameter to provide dynamic input for the source path (for example, servicepath/##servicename##?symbol=##id##).
On the Parameters page, supply default values for any parameters you specified, and click Next.

For the PUT and POST operations, you must also provide a URL that points to the XML schema definition that defines the format of the input.
On the Data Format page, select the data format of the data source and set the associated properties, then click Next.

You can choose either XML format (for which you provide URLs for the XSD and XSL) or delimiter separated value (for which you specify the delimiter, text qualifier, and encoding for the data).
On the Finish page, you can click Test URL Connection to verify that the URL data connection is valid, and click Finish.
Repeat the above steps for any other operation you would like to include in the data control. In order to include the additional operations in the same data control, fill in the Name field of the Data Source page of the wizard with the same name for the data control that you used when you ran the wizard for the first operation.

15.2.3 What Happens When You Create a URL Service Data Control

When you create a URL Service data control, the DataControls.dcx overview editor is populated with method nodes for each of your operations. Those method nodes may have Return subnodes, which in turn can contain subnodes for collections, scalar values, and attributes.

For operations on which you have selected the Include HTTP Header Parameter checkbox, an input parameter called HttpHeader and of type java.util.Map is specified for the method node.

For operations that take a parameter of a complex data type, an accessor return node also appears.

See Table 15-1 for the full list of the nodes that appear for URL service data controls and information on how you can use them.

15.2.4 How to Include a Custom Header Parameter for a URL Service Data Control

When using a URL service data control, you may want to add a custom parameter to the HTTP header when invoking the HTTP request. Such a parameter can be useful for a variety of purposes, including for security or for notifications.

Before you begin:

It may be helpful to have an understanding of how URL service data controls are used in ADF applications. For more information, see Section 15.1, "About Using ADF Model with URL Services."

You need to complete these tasks:

Create a URL Service data control and select the Include HTTP Header Parameter checkbox in the wizard. For more information, see Section 15.2.2, "How to Create a URL Service Data Control."
Create a managed bean and register it in the view project's adfc-config.xml file. For more information, see Section 24.4, "Using a Managed Bean in a Fusion Web Application."

To pass a custom header to a URL service:

In the managed bean, create a bean property of type java.util.Map that provides the header parameter names and values. The Map must be of type <String, List<String>> or <String,String>.

See Example 15-2 for an example of such a managed bean.
From the Data Controls panel, drag the method that includes the custom header parameter to a web page and drop it as an ADF Button.
In the Edit Action Binding dialog, perform the following steps to create the binding between the button and the managed bean:
1. In the Data Collection tree, select the method that includes the HTTP header parameter.
2. In the Parameters table, click in the Value cell for the parameter, click the drop-down button, and then choose Show EL Expression Builder.
3. In the Variables dialog, type the expression by hand or generate the expression by navigating through the Variables tree and selecting the managed bean field that represents the HTTP parameter to which you are binding.
  
  For example, to bind to the httpHeadersMap property shown in Example 15-2, you would expand the ADF Managed Beans node, expand the node for the bean's scope, expand the node for name of the bean specified in the adfc-config.xml file (which is not necessarily the same as the class name), and select httpHeadersMap.

At runtime, the data control will obtain the entries from the map (if it is present) and add them as HTTP headers in the request.

Example 15-2 Managed Bean Containing Custom Parameters for URL Service Data Control

package view;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class BackingBean {    
    private Map<String,String> httpHeadersMap = new HashMap<String,String>();

      public BackingBean() {
          List<String> headersList = new ArrayList<String>();
          headersList.add("OurCompany");
          httpHeadersMap.put("TenantID","OurCompany"); 
      }
      public void setHttpHeadersMap(Map<String,String> httpHeadersMap) {
          this.httpHeadersMap = httpHeadersMap;
      }

      public Map<String,String> getHttpHeadersMap() {
          return httpHeadersMap;
      }
}

15.2.5 What You May Need to Know About Primary Keys in URL Service Data Controls

When you create a data control on a URL service, the data control supports primary key operations on any exposed collection. This feature is the same as the corresponding feature for web service data controls. For more information, see Section 14.2.5, "What You May Need to Know About Primary Keys in Web Service Data Controls."

15.2.6 What You May Need to Know About URL Service Data Controls

Because the URL Service data control is not updatable, there are limitations on some of the objects in the Data Controls panel. For example, the only built-in operations available under the Operations node are for retrieval and navigation. Also, in a URL Service data control, the parameter object is the parameter that a user passes in the URL For more information, see Table 15-1.

15.3 Using URL Service Data Controls

As with other kinds of data controls, you can design a databound user interface by dragging an item from the Data Controls panel and dropping it on a page as a specific UI component. For more information, see Section 13.4.1, "How to Use the Data Controls Panel."

In the Data Controls panel, each data control object is represented by an icon. Table 15-1 describes what each icon represents, where it appears in the Data Controls panel hierarchy, and what components it can be used to create.

Table 15-1 Data Controls Panel Icons and Object Hierarchy for the URL Service Data Control

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 the child objects listed under the data control. There may be more than one data control, each representing a logical grouping of data functions. Typically, there is one data control for a given source. However, you may have additional data controls that were created for other types of objects (for example, application modules or web services).	Serves as a container for the other objects. Not used to create anything.
Method	Represents a `loadData()` operation, which retrieves the contents of a URL. The operation may accept parameters, perform some action or business logic, and return data or data collections. If the operation returns a data collection, a method return icon appears as a child under it. If the operation requires a parameter, a folder appears under the method, which lists the required parameters.	UI actions such as buttons or links.
Method Return	Represents a data collection that is returned by a custom method. A method return appears as a child under the method that returns it. The objects that appear as children under a method return may be attributes of the collection, accessor returns that represent collections related to the parent collection, other methods that perform actions related to the parent collection, and operations that can be performed on the parent collection.	Forms, tables, trees, and range navigation components.
Accessor Return	Represents an object returned by an operation on the business service. An accessor method is used when the objects returned are complex types. Accessor returns are objects that are related to the current object in the parent collection. This relationship is usually based on a common unique attribute in both objects. For example, if a method returns a collection of users, an accessor return that is a child of that collection might be a collection of service requests that are assigned to a particular user. In ADF, the relationship between parent and child collections is called a master-detail relationship. For more information about master-detail objects, see Chapter 29, "Displaying Master-Detail Data." Accessor returns can be either collections or single complex objects. For example, if a method returns a collection of service requests, one accessor return under that method might be a collection of service history details for the current service request, while another accessor return might be a single user assigned to the current service request. The UI components available from the Data Controls panel context menu differ depending on whether the accessor return is a collection or a single object. The children under an accessor return may be attributes of the collection or object, other accessor returns, custom methods that return a value from the collection or object, and operations that can be performed on the collection or object.	For collections: Forms, tables, trees, range navigation components, and master-detail widgets. For single objects: Forms, master-detail widgets, and selection lists. For single objects under a constructor: selection lists only.
Attribute	Represents a discrete data element in an object. Attributes appear as children under method returns or accessor returns.	Label, text field, and selection list components.
Operation	Represents a built-in data control operation that performs actions on the parent object. If an operation requires a parameter, a folder appears under the method, which lists the required parameters. Data control operations are located in an Operations node under method returns or accessor returns and under the root data control node. The operations that are children of a particular method or accessor return operate on that return object only, while operations under the data control node operate on all the objects represented by the data control. Because the URL Service data control is not updateable, only retrieval and navigation operations are available.	UI actions such as buttons or links.
Parameter	Represents a parameter value that is declared by the method or operation under which it appears. Parameters appear in a folder under a method or operation. The parameter for a URL Service data control is the parameter that a user passes in the URL. These show up as a parameters to the `loadData()` method when the URL Service data control is created. For example, say you create a data control to the URL `http://www.example.org?id=##param##`. On the Data Controls panel, you would see that the `loadData()` method has one parameter with the name `param`. The value supplied to this parameter is substituted in the URL when the invocation occurs.	Label, text, and selection list components.