15 Exposing URL Services Using the ADF Model Layer

This chapter explains how to expose URL services using the ADF Model layer.

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 the data stream from a specified URL. Each URL service data control represents a single operation of the service. For example, the GET operation and the PUT operation for a given URL service are represented by two different data controls. Typically, all of the actions for a given URL service will share a common URL connection.

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 HTTP Method dropdown, choose the action for this 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.

15.2.3 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 Create Method object is not available and the only operations available are 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 custom method on the data control that may accept parameters, perform some action or business logic, and return data or data collections. If the method is a `get` method of a `map` and returns a data collection, a method return icon appears as a child under it. If a method requires a parameter, a folder appears under the method, which lists the required parameters. The URL Service data control exposes only one method `loadData()` which retrieves the contents of the URL.	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 a bean-style accessor method on the business service. An accessor method is used when the objects returned are JavaBeans. Accessor returns appear as children under method returns, other accessor returns, or in the Attributes node under built-in create methods. 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 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. By default, when data controls are created from session beans over POJOs, the names of accessors that return collections end in `Collection` (for example, `OrderCollection`). 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. The accessor returns under a built-in create method are always a single object and never have any children.	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.