16 Creating RESTful Web Services with Application Modules

This chapter describes how to create ADF REST resources based on view object instances of the ADF application module to make these resources available as RESTful web services in a Fusion web application.

This chapter includes the following sections:

16.1 About RESTful Web Services and ADF Business Components

ADF Business Components view object instances can be served as web services using REST. Client developers interact with these resources through the REST API enabled by the ADF REST runtime..

REpresentational State Transfer (REST) supports a stateless client-server architecture in which the web services are viewed as resources identified by their URL. HTTP Request methods such as GET and POST are the verbs that the developer can use in a web service client request message to describe the necessary create, read, update, and delete (CRUD) actions to be performed on the resource represented by the HTTP URL. REST prescribes the use of standards such as HTTP, URL, URI, XML, HTML, as well as Resource Types and MIME Types. Therefore, REST is not a standard but a proposed architectural style for web services.

Web services conforming to the REST design constraints are referred to as being RESTful. This type of web service allows the HTTP client and the HTTP server to exchange information about resources identified by using a URL. The request and response contain a representation of the resource, in a specific format, which defines the state of the actual resource.

In the Fusion web application, ADF REST resources acted on by RESTful web services are backed by view object instances exposed in the data model of the ADF Business Components Model project. ADF Business Components developers working in the ADF Model project can decide on the set of attributes to expose from backing view objects, the actions to make available (both standard CRUD operations and custom methods defined by either a view object interface or view row interface), and the view link relationships to preserve for the resulting resource.

Note:

When you create view objects that you intend to expose as ADF REST resources, use the Declarative option on the Query page of the Create View Object wizard to create view objects with declarative SQL mode option enabled. View objects created in declarative SQL mode at design time support an ADF REST framework runtime optimization that allows resource collections to be efficiently filtered by client requests made with the URL query parameter fields.

The design-time choices made by ADF Business Components developers are captured in REST resource definition XML files. Web service client developers may interact with these resource definitions through the REST API enabled by the ADF REST runtime. As a result, the consuming service client may invoke CRUD operations to interact with the REST resources and ADF business objects. The data is shaped by the resource's backing view object instance, with the parent-child relationships intact.

When you create the first REST resource in the ADF Business Components project, JDeveloper also generates a separate RESTful web service project to register the ADF REST servlet. Figure 16-1 shows the web.xml file that JDeveloper generates. You use this project to run and deploy the RESTful web service.

Figure 16-1 Applications Window Displays RESTful Web Service Project

This image is described in the surrounding text

Security for ADF REST resources is enforced in RESTful web services similar to the way you secure the Fusion web application. In JDeveloper, you run the Configure ADF Security wizard to enforce security on the ADF Model project. After you run the wizard, the REST resources of the deployed RESTful web service will be protected by default and will require that you grant access to the operations of the service.

You can test security in JDeveloper by creating test users and granting them access privileges to the resources. The security policies that confer these access rights, may then be migrated from the application level to a domain-level security policy store, where enterprise users are provisioned with access rights.

16.1.1 RESTful Web Services Use Cases and Examples

Any development team can publish an ADF REST resource to contribute to the Fusion web application. ADF REST application developers can manage the functionality that they expose to the service client using these version features:

  • Registering REST resources with an application-specific resource version name (or number) to support versioning of REST resources.

  • Declaring a default ADF REST framework version for REST resources allows service clients to utilize new features and enhancements at runtime, such as the advanced query capabilities offered in version 2 of the ADF REST runtime framework. By declaring a default framework version to process requests, REST application developers may opt into the features introduced by a specific ADF REST framework when they are ready. In JDeveloper release 12.2.1.2.0, framework versions 1, 2, and 3 exist.

Specific runtime features of the ADF REST framework that support the exchange of resource information by client and server include:

  • Interacting with the REST resource is supported by separate JSON-based media type structures for the resource, action execution, and the results of action execution.

  • Passing a custom header to specify the version of the ADF REST runtime framework that will be used to process requests. The version header allows service clients to override the default version declaration defined by the REST application. In JDeveloper release 12.2.1.2.0, framework versions 1, 2, 3 exist.

  • Interacting with the REST resource using standard HTTP request methods, including GET, POST, PATCH, and DELETE.

  • Executing an HTTP method using an X-HTTP-Method-Override header on a POST request method when client restrictions prevent the use of standard HTTP methods to interact with the REST resource.

  • Locating a REST resource item (such as a specific employee) or REST resource collection (such as an collection of all employees) is supported by REST-compliant URI path names based on resource names defined in the ADF Business Components Model project.

  • Obtaining a description of the REST resource, including the resource attributes and available actions, is supported by a specific media type and describe action.

  • Linking to a canonical REST resource is supported when a resource with a super set of updatable entities is defined. The canonical link supports alternate links for the backing view object.

  • Filtering of the REST resource is supported by query string parameters on the URI specified by the client to access the specific resource.

  • Encoding formats are supported on the REST resource to enable compression and decompression.

  • Content streaming of BLOB and CLOB attributes exposed by the REST resource is supported by the ADF REST framework.

  • Performing data consistency checks while invoking the RESTful web service is supported by the ADF REST framework. This capability uses version history in the database to enable clients to manage HTTP payloads according to updates in the resource itself.

  • Authorizing users to access the REST resource is enabled by ADF Security permission grants.

16.1.2 Additional Functionality for RESTful Web Services

You may find it helpful to understand other Oracle ADF features before you start working with RESTful web services. Following are links to supporting functionality that may be of interest.

16.2 Creating ADF REST Resources Using the Application Module

You can use ADF Business Components application module data model view objects instances to create the ADF REST resource.

The application module is an ADF Business Components framework component that encapsulates business logic as a set of related business functions exposed as view object instances and custom methods. You may map one or more view object instances that appear in the application module data model to ADF REST resources. You use the overview editor for your application module to create the ADF REST resource. The REST resource that you add to the ADF Model project may be published as a web service that follows the REST architectural style.

Note:

When you create view objects that you intend to expose as ADF REST resources, use the Declarative option on the Query page of the Create View Object wizard to create view objects with declarative SQL mode option enabled. View objects created in declarative SQL mode at design time support an ADF REST framework runtime optimization that allows resource collections to be efficiently filtered by client requests made with the URL query parameter fields.

16.2.1 How to Create ADF REST Resources from View Object Instances

View object instances are the business objects on which the Fusion web application operates. The ADF application module exposes these business objects in the data model it defines to specify the data that the service client can display and manipulate. ADF REST resources are defined directly against view object instances, using the overview editor for the application module.

Adding an ADF REST resource is an option that appears in the Web Service page of the application module overview editor. Figure 16-2 shows how the editor displays the REST resources that have been created for view object instances on the AppModule application module. Notice that the editor organizes REST resources on the application module by their assigned release-specific version names (in this example, named 11.0, 11.1, and 11.2).

Figure 16-2 ADF REST Resources Defined on the Application Module

This image is described in the surrounding text

Note:

When you create an ADF REST resource JDeveloper prompts you to specify a version release name for the resource. The version is an alphanumeric identifier that helps you to manage the current and subsequent versions of resources that you add to the ADF Model project across multiple releases.

After you select the view object instance, name the REST resource, and select a version, JDeveloper opens the resource in the overview editor for the REST resource. You use the overview editor to edit the REST resource representation by exposing view object accessors, available operations, and custom methods as payload objects and actions of RESTful web services. JDeveloper saves the REST resource definition files as subpackages of the ADF application module organized by their assigned release version names.

For details about customizing the REST resource, see How to Edit the ADF REST Resource Definition.

Before you begin:

It may be helpful to have an understanding of how the ADF REST framework supports application modules and enables web service clients to access rows of data and perform service operations. For more information, see About RESTful Web Services and ADF Business Components.

You may also find it helpful to understand other Oracle ADF features that depend on ADF REST resources. For more information, see Additional Functionality for RESTful Web Services.

You will need to complete these tasks:

  • Create the application module data model that contains the view object instances that you want the REST resource to expose, as described in How to Create an Application Module.

  • Create a release version identifier in the adf-config.xml file to associate ADF REST resources you create with a specific version. Each REST resource must be associated with a release version to help manage the current and subsequent versions of ADF REST resources that you add to the ADF Model project, as described in Versioning the ADF REST Resource.

To create the ADF REST resource:

  1. In the Applications window, double-click the application module that contains the view instance for which you want to create the ADF REST resource.

  2. In the overview editor, click the Web Service navigation tab, then click the REST tab, and then click the Enable Support for REST Service add icon.

    When you create the first REST resource, JDeveloper also generates a separate RESTful web service project to register the ADF REST servlet.

  3. In Create REST Resource dialog, select the root view instance to expose in a RESTful web service.

    The dialog displays view instances defined in the application module data model. Only the root view instance of a master-detail hierarchy may be selected.

  4. Enter the Resource Name of the REST resource collection and select a release version from the dropdown list, and then click OK.

    The resource name is the identifier that service clients use to interact with view instance. For example, as the following figure shows, to name a collection based on a DeptView1 view instance, you might name enter Departments to indicate the full collection name. For more information about naming, see What You May Need to Know About Naming ADF REST Resources.

    The release version is an identifier that you must create in the adf-config.xml file to manage the creation of resources in JDeveloper. The version will be part of the URL that service clients use to invoke operations on a specific REST resource, as described in Versioning the ADF REST Resource.

    Figure 16-3 Assigning the ADF REST Resource to a Release Version

    This image is described in the surrounding text
  5. In the overview editor for the REST resource, you can proceed to edit the resource and its structure by performing any of the following tasks:

    1. Add and remove child resources defined by view link accessors. For details, see How to Edit the ADF REST Resource Definition.

    2. Add and remove resources defined by the same backing view instance. For details, see How to Add and Remove Resources Based on the Same View Instance.

    3. Add and remove attributes. For details, see How to Hide and Expose Attributes in the ADF REST Resource.

    4. Modify access to standard operations defined by HTTP methods, canonical links, row finder filters, subtype view usages, and custom methods. For details, see Customizing the ADF REST Resource Representation and Methods.

  6. Click File and then Save All to save the selections on this resource.

    JDeveloper saves the REST resource selections that you make in the overview editor in the resource definition file for the resource, as described in What Happens When You Create REST Resources in the ADF Business Components Project.

16.2.2 What Happens When You Create REST Resources in the ADF Business Components Project

JDeveloper generates the REST resources and displays them in the Applications window organized in the model project by their version release names, as shown in Figure 16-4.

JDeveloper also generates a separate RESTful web service project (RESTWebService) to register the ADF REST servlet. Figure 16-4 shows the web.xml file that JDeveloper generates. You use this project to run and deploy the RESTful web service.

The ResourceRegistry.rpx file that appears in the model project uses metadata annotations to specifies the list of REST resources that will be exposed as a RESTful web service.

The adf-config.xml file is updated when you create the version release names. This file appears in the Applications window in the Application Resources panel, under the Descriptors and ADF META-INF nodes. The connections.xml file in the same folder is created when you first create the ADF Business Components.

Figure 16-4 REST Resources Appear Below Application Module Node

This image is described in the surrounding text

16.2.3 How to Edit the ADF REST Resource Definition

After you add an ADF REST resource definition to the ADF Model project, the REST section of the application module overview editor displays the names of the resources you have created. You can open the REST resource definition in its own editor by clicking the resource name in the list (as shown in Figure 16-2 ).

The overview editor for REST resources displays the options for editing the structure of the resource. From the standpoint of the RESTful web service, the REST resource structure determines the available data that may be invoked by REST calls at runtime.

At design time, you can edit the REST resource definition to select only the resources that you want to expose from the view object hierarchy backing the resource. When you first create a REST resource, you are required to select a view object exposed by the data model of the application module to back the resource. This original view object selection defines the root resource of the REST resource. You may optionally expose additional child view objects if present.

For example, the left side of the REST resource editor shown in Figure 16-5 displays the default structure of the resource, Departments. The resource structure appears as a tree with the root node representing the root resource (in this case DepartmentsView1). The leaf nodes of the tree represent child resources. In this example, the Departments resource is comprised of a root resource DepartmentsView1 and various child resources, including Employees and JobHistory. Because the DepartmentsView1, Employees, and JobHistory resources are related as view instances in the data model, they appear in the hierarchy. You use the checkboxes beside leaf nodes to add and remove child resources from the resource structure.

Figure 16-5 Overview Editor Displays Resource Structure

This image is described in the surrounding text

Note:

The right side of the REST resource editor displays the available options corresponding to the node selections that you make in the Structure tree.

Table 16-1 summarizes the nodes of the resource structure tree:

Table 16-1 Nodes of the Resource Structure Tree

Node Description Editing Options

Root resource node:

icon

Represents the view object instance that backs the root resource selection.

The backing view object instance of the root resource cannot be altered or removed.

You may select this node to select options on the root resource. For details about these options, see Customizing the ADF REST Resource Representation and Methods.

Child resource node:

icon

Represents a view link accessor used in the data model to define master-details relationships defined for the view object instance that backs the root resource selection.

Note: Child nodes are not displayed when the view object instance of the root resource is not included in a master-detail relationship.

Child resources are disabled by default. Select the checkbox to expose a child resource in the resource representation. To remove a child resource from the resource representation, deselect the checkbox.

You may select a child resource node to select options on the child resource. For details about these options, see Customizing the ADF REST Resource Representation and Methods.

Before you begin:

It may be helpful to have an understanding of how ADF REST supports application modules and enables web service clients to access rows of data and perform service operations. See About RESTful Web Services and ADF Business Components.

You may also find it helpful to understand other Oracle ADF features that depend on ADF REST resources. See Additional Functionality for RESTful Web Services.

You will need to complete this task:

To edit the ADF REST resource structure:

  1. In the Applications window, double-click the resource definition file that defines the ADF REST resource you want to edit.
  2. In the overview editor, make the desired selections.

    Press F1 to view the JDeveloper Help Center topic for the overview editor.

  3. Choose File and then Save All to save the changes on this resource.

    JDeveloper saves your changes in the resource definition file for the resource, as described in What Happens When You Create REST Resources in the ADF Business Components Project.

16.2.4 How to Expose Child Resources in the ADF REST Resource

Child resources may be exposed in the ADF REST resource when the application module data model specifies one or more hierarchical, master-detail relationships. For each master-detail relationship in the data model, the ADF Business Components Model project must define a view link accessor that names the related parent and child view objects, thereby nesting the child or detail view object instance within the parent or master view object instance.

At runtime, a REST resource that exposes nested view instances supports returning collections for the master and detail in a single roundtrip. Thus, exposing child resources at design-time is useful for service clients with the requirement to manipulate master-detail data.

In JDeveloper, the overview editor for REST resources displays master-detail relationships as a resource structure tree with child resources displayed as leaf nodes of the root resource. For example, Figure 16-6 shows the Departments resource in the overview editor with the following nested resource structure:

  • DepartmentsView1 is the master view instance and backs the root resource.

  • Employees is a detail view instance, nested below DepartmentsView1 and the checkbox for the tree node appears selected, indicating the Departments resource exposes the child resource.

  • JobHistory is another detail view instance, nested below EmployeesView and the checkbox for the tree node appears selected, indicating the Departments resource exposes the child resource.

By default, JDeveloper creates the REST resource based on the selected backing view instance, but does not include child resources. In the resource structure tree, child resources appear unselected by default to indicate that these resources are not exposed. You may expose or hide child resources, by selecting or unselecting its checkbox.

Figure 16-6 Child Resources Enabled in the Overview Editor

This image is described in the surrounding text

Note:

By default, child resources are not exposed and must be selected in the overview editor to expose them in the resource.

Before you begin:

It may be helpful to have an understanding of how ADF REST supports application modules and enables service clients to access rows of data and perform service operations. For more information, see About RESTful Web Services and ADF Business Components.

You may also find it helpful to understand other Oracle ADF features that depend on ADF REST resources. For more information, see Additional Functionality for RESTful Web Services.

You will need to complete this task:

To expose nested resources:

  1. In the Applications window, double-click the resource definition file that defines the ADF REST resource you want to edit.
  2. In the overview editor for the REST resource, expand the Structure tree and select the checkbox of any child resource of the root resource.

    By default, child resource nodes appear unselected in the Structure tree, which indicates that nested resources are unexposed in the resource.

    If the data model does not define a master-detail hierarchy for the backing view instance of the root resource, then no child resource node will appear in the Structure tree. For more information about Structure nodes, see Table 16-1.

  3. Select the checkbox of another child resource in the Structure tree to enable its nested resource on the resource.

16.2.5 How to Add and Remove Resources Based on the Same View Instance

In JDeveloper, you can use the overview editor for REST resources to define multiple resources for the same view instance. You might add a resource when a single resource definition does not support all of the use cases of your service client. After you add a resource you will be able to modify the operations, list of attributes, and other items of the resource structure to support the desired use cases. Because each resource you define represents a unique resource collection to the service client, resource names should reflect the differences.

The overview editor for REST resources displays the list of resources you add in the Resource dropdown. For example, Figure 16-7 shows the Employees resource and the EmployeesAllAttrs resource in the overview editor for the same backing view object EmployeesView.

Figure 16-7 Resource List Supports Multiple Resource in the REST Resource Definition

This image is described in the surrounding text

Note:

JDeveloper lets you remove resource definitions that have been added in the overview editor for REST resources. However, the empty definition file will appear in the Applications window.

Before you begin:

It may be helpful to have an understanding of how the ADF REST framework supports application modules and enables service clients to access rows of data and perform service operations. For more information, see About RESTful Web Services and ADF Business Components.

You may also find it helpful to understand other Oracle ADF features that depend on ADF REST resources. For more information, see Additional Functionality for RESTful Web Services.

You will need to complete this task:

To add and remove resources in the overview editor:

  1. In the Applications window, double-click the resource definition file that defines the ADF REST resource for which you want to add or remove resources.

  2. In the overview editor for the REST resource, choose the resource from the Resource dropdown and then click Delete Resource to delete a resource that has already been defined for the view object.

    If you delete the root resource definition using Delete Resource, the resource is deleted, but the empty definition file will appear in the Applications window.

  3. In the overview editor for the REST resource, to add a resource that you will create for the view object, click Add Resource.

  4. In the Add Resource for View Object dialog, enter the Resource Name of the REST resource collection that you want to add for the selected root view instance and then click OK.

  5. In the overview editor for the REST resource, select the new resource from the Resource dropdown to edit its resource definition:

    1. Add and remove child resources defined by view link accessors. For details, see How to Edit the ADF REST Resource Definition.

    2. Add and remove attributes. For details, see How to Hide and Expose Attributes in the ADF REST Resource.

    3. Modify access to standard operations defined by HTTP methods, canonical links, row finder filters, subtype view usages, and custom methods. For details, see Customizing the ADF REST Resource Representation and Methods.

16.2.6 How to Hide a Resource from the Catalog Describe

You can hide a top-level resource from the ADF REST catalog describe by setting the Visibility attribute within the ServiceConfiguration tag in the resource definition as shown in the following code example.

<tree..>
  <ServiceConfiguration Visibility="unlisted"/> 
   ...
</tree>

You can set the Visibility attribute to unlisted or public. You can use the include query parameter to include the description of resources of a certain visibility. For more information, see Describing All Available Resources.

16.2.7 How to Rename the ADF REST Resource

During development of ADF REST resources you may use the overview editor for REST resources to change the name of a resource in the resource definition file. Because service clients use the resource names to interact with the desired REST resource collections, it is important that you finalize the names of ADF REST resources before deploying the service to a production environment.

When you need to change the name of an ADF REST resource after deployment, this is best handled by creating an entirely new version of the resource, as described How to Version the ADF REST Resource.

Before you begin:

It may be helpful to have an understanding of how the ADF REST framework supports application modules and enables service clients to access rows of data and perform service operations. For more information, see About RESTful Web Services and ADF Business Components.

You may also find it helpful to understand other Oracle ADF features that depend on ADF REST resources. For more information, see Additional Functionality for RESTful Web Services.

You will need to complete this task:

To rename a resource before production deployment:

  1. In the Applications window, double-click the resource definition file that defines the ADF REST resource you want to rename.
  2. In the overview editor for the REST resource, choose the desired resource from the Resource dropdown.

    If you have not created additional resources on the resource definition file, the list displays the original resource created for the backing view object.

  3. Click the Representation tab of the overview editor and enter the new name in the Resource Name field.

16.2.8 What You May Need to Know About Naming ADF REST Resources

The REST resource name is the way service clients identify and interact with exposed resource collections. REST resource names typically identify the view object the consuming client is to access. As such, REST resource names are nouns, not verbs.

16.2.9 How to Hide and Expose Attributes in the ADF REST Resource

In JDeveloper, you can use the overview editor for REST resources to define multiple resources for the same view instance. You might add a resource when a single resource definition does not support all of the use cases of your service client. After you add a resource, you can modify the list of exposed attributes, and other items of the resource structure, as needed to support the desired use cases.

The overview editor for REST resources displays the list of exposed attributes in the Attributes tab. The list is populated by a REST service shape selection that you define on the view object backing the root resource. For example, Figure 16-8 shows the service shape definition EmployeesView_ForHR that exposes all but two of the attributes for the EmployeesView view object.

Figure 16-8 Attributes Exposed By REST Service Shape Definition Selection

This image is described in the surrounding text

Note:

You do not directly modify the list of exposed attributes in the overview editor for REST resources. Rather, you must create service shape definitions on the backing view object, and you then apply the desired REST Shape definition to the current Resource dropdown selection.

To support the use cases of service clients, you can define as many service shape definitions for each view object as required. The Applications window displays service shape definitions that you create for the view object in the persdef folder under the view object node. For example, Figure 16-9 shows two service shape definition files EmployeesView_forHR.xml and EmployeesView_ForBenefits.xml beneath the EmployeesView view object.

Figure 16-9 REST Service Shape Definition Files in the Applications Window

This image is described in the surrounding text

Before you begin:

It may be helpful to have an understanding of how the ADF REST framework supports application modules and enables service clients to access rows of data and perform service operations. For more information, see About RESTful Web Services and ADF Business Components.

You may also find it helpful to understand other Oracle ADF features that depend on ADF REST resources. For more information, see Additional Functionality for RESTful Web Services.

You will need to complete this task:

To apply a REST service shape definition to a REST resource:

  1. In the Applications window, double-click the resource definition file that defines the ADF REST resource you want to edit.
  2. In the overview editor for the REST resource, click the View Object link.
  3. In the overview editor for the view object, click the Service Shape navigation tab.
  4. In the Service Shaping page, click the Create Service Shaping Object button and then in the Create Service Shape dialog, enter a suffix name to uniquely identify the service shape definition.

    The suffix you enter forms the name of the service shape definition file. For example, the suffix ForHR is added to the view object EmployeesView to form the service shape definition name EmployeesView_ForHR, as shown in Figure 16-10.

    Figure 16-10 View Object Service Shape Definition Defines Available Attributes

    This image is described in the surrounding text
  5. In the Service Shaping page, use the shuttle buttons to alter the list of Hidden and Selected attributes and save the view object definition.

    When you alter the service shape in the overview editor for REST resources, JDeveloper updates the service shape definition file for the view object. The resource structure of any ADF REST resource that references the service shape will be updated as well.

  6. In the overview editor for the REST resource, select the desired resource from the Resource dropdown.
  7. Click the Attributes tab of the overview editor, and then select the Service Shaping Object that defines the list of attributes that you want to expose.

16.2.10 What You May Need to Know About Modifying the ADF REST Resource Structure

As shown in Figure 16-11, after you create the resource and assign a version identifier, the overview editor for the REST resource displays the version in the top, right corner of the editor to help you identify which version you are editing.

Figure 16-11 REST Resource Editor Displays Version

This image is described in the surrounding text

Changes that you make to ADF REST resources during the development cycle can be made without the need to version the resource. However, once you have deployed the RESTful web service, service clients that access the ADF REST resources rely on the stability of the resource collection to satisfy their use cases.

Over time, as use cases change or the backing view objects of the REST resources change, you may need to modify the resource structure of already deployed resources. At that time, modifications to existing ADF REST resources may become backward-incompatible with the deployed REST service and may necessitate creating a new version identifier and ADF REST resource for that version. For details about when to version the REST resource, see What You May Need to Know About Versioning ADF REST Resources.

JDeveloper lets you manage resource versions in the Release Versions page of the overview editor for the adf-config.xml file in the ADF META-INF folder. For details about how to create a new version of ADF REST resources, see Versioning the ADF REST Resource.

16.2.11 What You May Need to Know About ADF REST Resources and LOB Attributes

A resource that exposes a BLOB or CLOB type attribute will be accessible at runtime as streaming media. By default, the view object attribute will be handled by the ADF REST runtime using the generic content type application/octet-stream. When you want to support a specific content type, you can configure the special property contentType as a custom property of the LOB-type attribute. For example, when working with PNG image files, the following content type can be configured at design time.

  • Custom Property: contentType

  • Value: image/png

As Figure 16-12 shows, the custom property contentType has been added to the view object definition for the Picture attribute in the overview editor for the view object.

Figure 16-12 Custom Content Type Configured for LOB Attributes

This image is described in the surrounding text

16.2.12 What You May Need to Know About LOV Accessors in the ADF REST Resource

A list of value (LOV) attribute is any attribute of a view object that relies on another view object as its data source. Typically, the data source view object specifies a fixed list of possible values for the LOV-enabled attribute. When you explicitly define an LOV-enabled attribute on a view object, ADF Business Components defines an LOV view accessor that the ADF REST runtime will automatically expose in the ADF REST resource as a LOV child resource. Thus, at runtime when an LOV-enable attribute is detected on a resource, service clients may invoke LOV view accessors to obtain the data source of an LOV-enabled attribute and present selection choices to the end user.

Note:

By default, LOV accessor resources are exposed on resources and are not displayed in the structure tree of the resource overview editor. For details about creating LOV-enabled attributes, see Working with List of Values (LOV) in View Object Attributes.

16.2.13 What You May Need to Know About Case Sensitivity in Resource Collection Query Operations

The ADF REST framework supports case insensitive search when using a q query parameter to filter search results. The flag named restV1QueryCaseSensitive in the adf-config.xml file can be set to false if you want to perform case insensitive search. The default value of the flag is true which implies case sensitive search.

16.3 Customizing the ADF REST Resource Representation and Methods

JDeveloper allows you to edit the ADF REST resource definition. You can enable HTTP actions, expose a row finder, enable a canonical resource link for each node of the tree etc.

You use the overview editor for the ADF REST resource to edit the ADF REST resource definition. Selections that you make in the resource structure tree let you enable HTTP actions, expose a row finder, and enable a canonical resource link for each node of the tree.

The customization choices that you make for REST resources in your ADF Model project ultimately affect the ability of service clients to interact with these resources at runtime. Therefore it is important to understand the requirements of the service client use cases to support the desired ADF REST runtime features though the various design time customizations described in this section.

For details about the ADF REST runtime, see Consuming RESTful Web Services Using the ADF REST Framework.

Note:

Custom properties defined for a resource attribute are included in the describe. However, custom properties whose name begins with INTERNAL, internal, or __ (double underscore), are hidden from the describe.

16.3.1 How to Expose Canonical Resources in the ADF REST Resource

The ADF REST resource representation limits the attributes returned in a runtime response to the attributes queried by the resource's backing view object. When defining the view object query at design time, it is therefore important to expose only the attributes required to support specific use cases of the service client. However, in order to allow the service client to navigate from the partial REST resource representation to the full representation of the same data, you can configure a link to a canonical resource.

Typically, the canonical resource is considered as the source of truth and therefore specifies the full representation of a given data source. An example of a canonical resource, can be illustrated by the employees resource with a link to a resource that describes a manager instance. In this scenario, where typical use cases may require only the manager name, the non-canonical manager resource includes only the name attribute. And, for cases where the name is not sufficient to identify the manager, the non-canonical resource may link to a canonical resource that exposes all attributes of the manager instance, including name, id, department, hire date, and so on. Thus, the canonical resource and the non-canonical resource exist as follows:

  • Non-canonical resources and the canonical resource expose different representations of the same data source.

  • Non-canonical resources expose only a representation of the data source needed to support service client use cases and are therefore a partial representation.

  • Non-canonical resources include a link to its canonical, full representation when defined.

In the overview editor for the resource, for each resource node in the resource structure tree, you may choose a canonical resource from an existing REST resource defined by the ADF Model project or you may choose an external resource defined by an existing URL connection in the connections.xml file of the application.

The internal canonical resource that you can select in the overview editor for REST resources, must meet the following criteria:

  1. Your ADF Model project must define a view object that accesses the same data source backing the existing, partial representation resource. The view object may or may not be entity-based.

  2. The view object must query a superset of available attributes queried by the non-canonical resources.

  3. The superset representation view object must be specified as a view instance on the data model of the application module.

Figure 16-13 shows the EmployeesView root resource node selection in the overview editor and the Resource dropdown selection HREmployees, with the internal canonical resource Employees enabled. In this case, the database table specified by each backing view object is the same for both the HREmployees and the Employees resource. In this example, Employees is the canonical resource and contains all attributes from the backing view object whereas the HREmployees resource is backed by the same view object but queries only the attributes required to support a specific use case.

Figure 16-13 Canonical Resource Enabled in the Overview Editor

This image is described in the surrounding text

Note:

A resource (resource_partial) can only select another resource as canonical (resource_full) as long as the resource_full contains all the attributes that resource_partial exposes.

Before you begin:

It may be helpful to have an understanding of how the ADF REST framework supports application modules and enables service clients to access rows of data and perform service operations. For more information, see About RESTful Web Services and ADF Business Components.

You may also find it helpful to understand other Oracle ADF features that depend on ADF REST resources. For more information, see Additional Functionality for RESTful Web Services.

You will need to complete these tasks:

  • Create the desired REST resource, as described in Creating ADF REST Resources Using the Application Module.

  • When you want the REST resource's canonical link to expose an internal canonical resource, create a view object definition that queries the superset of available attributes from the data source (must be the same data source as the non-canonical REST resource) and expose that view object in the data model, then create a resource for the internal canonical resource. For details about creating a resource, see How to Create ADF REST Resources from View Object Instances.

  • When you want the REST resource's canonical link to expose an external canonical resource, create a URL connection in the application connection file (connections.xml), as described in the “Create URL Connection Dialog” topic in the JDeveloper Online Help.

To expose a canonical resource link:

  1. In the Applications window, double-click the resource definition file that defines the ADF REST resource you want to edit.
  2. In the overview editor for the REST resource, choose the desired resource from the Resource dropdown, expand the Structure tree and select the node for which you want to define a canonical resource link.

    You can define a canonical link for each resource node in the resource tree. For more information about Structure nodes, see Table 16-1.

  3. With the resource node selected in the Structure tree, click the Representation tab of the overview editor, and then select Canonical Link.

    If you do not want to expose a canonical resource for the current resource accessor node selection, deselect Canonical Link.

  4. In the Canonical Link section, select whether the canonical resource is Internal or External and choose the desired resource from the dropdown list to represent the canonical version of the resource.

    The dropdown list for internal resources is populated by the resources that you added to the current resource; these are resources that are internal to the application and must be based on the same data source as the current resource.

    The dropdown list for external resources is populated by URL connections that you have defined for the application and registered in the application connection file (connections.xml).

16.3.2 How to Enable Row Finder Keys in the ADF REST Resource

When you do not want service clients to be able to query resources using the primary key for the resource (often a numeric value), the business components developer can create a row finder that specifies a row finder key based on a view object attribute with values that can be uniquely identified by name. One such example may find employees by the first letters of the email attribute.

When a row finder has been explicitly defined on the view object named in the ADF REST resource, the overview editor for the ADF REST resource gives you the option to enable the row finder to filter the resource collection. Row finders are not enabled by default; you must the select the row finder key by name to apply it the current node selection in the resource structure.

In JDeveloper, the overview editor for ADF REST resources displays the list of available row finders in the Rowfinder Key dropdown. The list is populated by the row finders that have been defined on the view object definition backing the node selection in the resource structure tree. For example, Figure 16-14 shows the EmpByEmailFinder row finder key where Employees is the node defining the view instance with the row finder EmpByEmailFinder.

Figure 16-14 Row Finder Key Enabled on the Root of the ADF REST Resource

This image is described in the surrounding text

Before you begin:

It may be helpful to have an understanding of how the ADF REST framework supports application modules and enables service clients to access rows of data and perform service operations. For more information, see About RESTful Web Services and ADF Business Components.

You may also find it helpful to understand other Oracle ADF features that depend on ADF REST resources. For more information, see Additional Functionality for RESTful Web Services.

You will need to complete these tasks:

To expose row finder filters:

  1. In the Applications window, double-click the resource definition file that defines the ADF REST resource you want to edit.
  2. In the overview editor for the REST resource, choose the desired resource from the Resource dropdown, expand the Structure tree and select the resource node for which you want to expose a row finder.

    If the data model does not define a master-detail hierarchy for the backing view instance of the root resource, then no view link accessor node will appear in the Structure tree. For more information about Structure nodes, see Table 16-1.

  3. Click the Representation tab of the overview editor, and then, in the Rowfinder key, select the row finder on the current Structure tree selection.

    The Rowfinder key dropdown may appear disabled if the resource enables a canonical link and the canonical resource itself enables a row finder key. The overview editor for ADF REST resources will disable the row finder key field and automatically reflect the row finder key on the partial resource, as described in What You May Need to Know About Row Finders in ADF REST Resource Requests.

  4. Optionally, click Canonical Link when you want the row finder selection to filter the canonical resource representing the current node selection.

    If you enable a canonical link, you must also select an internal or external source for the canonical resource.

  5. Select another node in the Structure tree to expose another row finder.

16.3.3 What You May Need to Know About Row Finders in ADF REST Resource Requests

At runtime, an ADF REST resource with a row finder key enabled must be accessed in the service client by the row finder key attribute. The row finder supports returning a collection or instance for the row finder-enabled resource using only the row finder key attribute. Thus, service clients may access REST resources without requiring knowledge of database primary key values to end users. For example, compare these two GET requests to retrieve a specific employee in the Employees resource collection:

No row finder:

http://localhost:7101/RESTSample_App/rest/11.1/Employees/101

With row finder

http://localhost:7101/RESTSample_App/rest/11.1/Employees/NSMITH

The first URL, with no row finder key defined, requires the ID of the employee to locate the employee resource item. The second URL uses the row finder key value (employee's email address) in the resource path. Once the row finder key has been enabled on the resource at design time, service clients may access the resource by row finder key values using links generated in the request payload by the ADF REST runtime.

You can optionally apply the row finder to a canonical resource that your ADF REST resource defines. If a canonical resource with row finder key is defined on the ADF REST resource with a row finder key enabled, then both sides must be defined by the same key structure. The key attributes must be of the same type and in the same sequence. When you create a canonical resource with a row finder key and then create a partial resource with a canonical link, the overview editor for ADF REST resources will disable the row finder key field and automatically reflect the row finder key on the partial resource. For details about canonical resources, see How to Expose Canonical Resources in the ADF REST Resource.

16.3.4 How to Expose Subtype View Object in the ADF REST Resource

A subtype view object is a view object that extends a base view object in an inheritance hierarchy. The subtype view object inherits its list of attributes from the base view object and contributes its own attributes that are specific to the subtype. Such subtype view objects are called polymorphic view objects. At runtime, polymorphic view objects define subtype view rows comprised of attributes from the base view object and attributes from the defining subtype view object.

In order to query subtype view rows, the subtype view object must specify a discriminator attribute that determines the specific type. For example, an EmployeesView base view object with a discriminator attribute JobId may instantiate subtype view rows based on the available jobs (Accountant, Sale Representative, and so on), where the attributes of subtype view rows are determined by the specified job ID value. For example, a Sales Representative with the job ID SA_REP might contribute the subtype view row attribute CommissionPct, whereas the subtype view rows for the other job types would omit this attribute.

The overview editor for REST resources lets you expose subtype view objects for each node of the Structure tree when the view object backing the node defines a discriminator attribute. For example, Figure 16-7 shows the Employees resource and the EmployeesView2 resource node selected in the overview editor. The backing view object EmployeesView defines the discriminator attribute JobId and the subtype view object SalesEmployeeView defines the subtype SA_REP. The editor exposes the SalesEmployeesView subtype view object by enabling Include Discriminator Subtype, specifying the Discriminator Name and omitting the discriminator attribute value. Omitting the JobId discriminator attribute value ensures that subtype attributes will be returned in service client requests for Employees based on the JobId value of the requested employee.

Figure 16-15 Defining a Discriminator Attribute in the REST Resource Definition

This image is described in the surrounding text

Note:

Discriminator attributes are defined on the backing view object and support subtype view rows. Subtype view objects are not exposed in the design time as ADF REST resources. The subtype definition is specified on the application module and by the ADF REST runtime.

Before you begin:

It may be helpful to have an understanding of how the ADF REST framework supports application modules and enables service clients to access rows of data and perform service operations. For more information, see About RESTful Web Services and ADF Business Components.

You may also find it helpful to understand how view objects support subtype view rows. For more information, see Working with Polymorphic View Rows.

You may also find it helpful to understand other Oracle ADF features that depend on ADF REST resources. For more information, see Additional Functionality for RESTful Web Services.

You will need to complete this task:

To expose subtype view rows in the resource definition:

  1. In the Applications window, double-click the resource definition file that defines the ADF REST resource you want to edit.
  2. In the overview editor for the REST resource, choose the desired resource from the Resource dropdown, expand the Structure tree and select the resource node for which you want to expose a subtype view object.

    If the data model does not define a master-detail hierarchy for the backing view instance of the root resource, then no view link accessor node will appear in the Structure tree. For more information about Structure nodes, see Table 16-1.

  3. Click the Representation tab of the overview editor, and then, select Include Discriminator Subtype to enable subtype view rows on the current Structure tree selection.
  4. Select the subtype discriminator attribute from the Discriminator Name dropdown and omit the value that defines the desired subtype view rows when the subtype view object defines the subtype discriminator attribute value.

    The Discriminator Name dropdown is populated by the discriminator attribute definition of the backing view object. For example, an EmployeesView view object might define the discriminator attribute JobId attribute as the discriminator attribute with a subtype view object SaleEmployeesView. In most cases, the subtype view object will define the subtype discriminator attribute value, and you can leave the attribute value empty in the resource definition. For example, where the subtype view object SalesEmployeesView defines SA_REP (Sales Representative) as the JobId discriminator attribute value, a request made for the Employees resource will contain the subtype attributes based on the employee's job ID and not by the subtype defined by the resource. Defining the discriminator attribute subtype value in the resource forces the resource items to the same type.

16.3.5 How to Expose Standard HTTP Actions in the ADF REST Resource

Standard data manipulation operations that you expose on the ADF REST resource correspond to actions on the backing view instance of the resource. At runtime, the service client invokes these operations as HTTP actions on the RESTful web service.

Table 16-2 lists the standard operations that are exposed by default in the overview editor for the REST resource. You can expose a different set of operations by deselecting operations from the list for each resource selection you make in the resource tree. Note that the GET method is always exposed for a resource.

Table 16-2 Standard View Instance Data Manipulation Operations

Operation Selection HTTP Method Name Operation Description

Create

POST

Creates an ADF Business Components view row or view row set.

Update

PATCH

Updates the specified items of an ADF Business Components view row. The view row must exist for this operation to succeed.

Delete

DELETE

Deletes an ADF Business Components view row or view row set.

not applicable

GET

Reads an ADF Business Components view row or view row set. Note that this operation is available by default when you create a resource.

Note:

Note that Oracle has deprecated the functionality for executing HTTP PUT methods on ADF REST resource requests. In the current release, the describe for ADF REST resources continues to display PUT actions when the backing view object has the Update operation enabled (the operation enables both PUT and PATCH methods); however, ADF REST service clients should avoid making PUT requests (replace all items of the view row) as this functionality will be desupported in a future release.

Before you begin:

It may be helpful to have an understanding of how the ADF REST framework supports application modules and enables service clients to access rows of data and perform service operations. For more information, see About RESTful Web Services and ADF Business Components.

You may also find it helpful to understand other Oracle ADF features that depend on ADF REST resources. For more information, see Additional Functionality for RESTful Web Services.

You will need to complete this task:

To expose HTTP actions:

  1. In the Applications window, double-click the resource definition file that defines the ADF REST resource you want to edit.
  2. In overview editor for the REST resource, choose the desired resource from the Resource dropdown, expand the Structure tree and select the resource accessor node that you want to edit.

    You can expose operations for root resources and child resources. For more information about Structure nodes, see Table 16-1.

  3. Click the Representation tab of the overview editor, and then, in the Available Operations section, select the operations to expose for the current Structure tree selection.
  4. Select another node in the Structure tree to expose operations on another resource accessor in the resource structure.

16.3.6 How to Support Create Operations on ADF REST Resources with LOV Attributes

When you want the ADF REST resource to support resource operations that require a list of values (LOV) without a row context to populate the list, you must create a LOV resource. For example, a service client may invoke a resource item create operation on the REST resource, in which case no row context will be available for the LOV list. In this situation, the LOV resource does not exist as a child resource and must instead be accessed at runtime by the service client independent from resource items that they attempt to create.

Note:

No design time changes are required to support resources with LOV-enabled attributes when the service client needs to access existing resource items. It is only necessary to create an LOV resource at design time when you want to enable service clients to create new resource items and the resource item is backed by an LOV-enabled attribute. In the case of existing resource items, the resource item provides a row context within the resource collection that allows the ADF REST runtime to automatically generate LOV links as a child resource. For more information about LOV child resources, see What You May Need to Know About LOV Accessors in the ADF REST Resource.

In JDeveloper, you use the overview editor for view objects to create LOV definitions for individual attributes in the Attributes page of the editor. The same page is used to define the static LOV resource. For example, Figure 16-16 shows the EmployeesView view object and the LOV-enabled attribute JobId in the overview editor for the view object backing the Employees resource. The static LOV resource is identified by the specific ADF REST resource that it supports: in this case, v2 (the internal version identifier of the Jobs resource). Below the static LOV resource is the LOV definition used by the LOV-enabled attribute of the view object.

Figure 16-16 Static LOV Resource Supports Create Operations on the REST Resource

This image is described in the surrounding text

Before you begin:

It may be helpful to have an understanding of how the ADF REST framework supports application modules and enables service clients to access rows of data and perform service operations. For more information, see About RESTful Web Services and ADF Business Components.

You may also find it helpful to understand other Oracle ADF features that depend on ADF REST resources. For more information, see Additional Functionality for RESTful Web Services.

You will need to complete this task:

Caution:

When the view object defines an LOV resource, the view object service shape definition must not hide attributes that are required by the LOV-enabled attribute's LOV definition. Required LOV attributes include attributes mapped to the LOV data source, as well as LOV display attributes. For more information about service shaping and ADF REST resources, see How to Hide and Expose Attributes in the ADF REST Resource.

To define a static LOV resource for use with ADF REST resources:

  1. In the Applications window, double-click the resource definition file that defines the ADF REST resource you want to edit.
  2. In the overview editor for the REST resource, click the View Object link.
  3. In the overview editor for the view object, click the Attributes navigation tab.
  4. In the Attributes page, expand the LOV section and click the Create LOV Resource on Attribute button.
  5. In the Create LOV Resource dialog, select the Release Version identifier, select the Resource Name for the ADF REST resource that exposes the LOV-enabled attribute, and then select the defining resource from the resource structure tree.

    The Resource Name list is populated by the ADF REST resource definitions in the Model project. The REST resource you select must have the same view object definition as the view object that defines the LOV attributes data source. For example, when creating an Employees resource, the EmployeesView view object defines an LOV attribute JobsId. In the Create LOV Resource editor, you would select the ADF REST resource Jobs and the root resource JobsView1 from the Jobs resources resource structure tree, as shown in Figure 16-17.

    Figure 16-17 Creating a Static LOV Resource for REST Create Operations

    This image is described in the surrounding text
  6. Click OK to save the LOV resource definition.

16.3.7 What You May Need to Know About Optimizing ADF REST Resource Get Operations

All ADF REST resources support read operations by service clients. To support efficient read operations (HTTP GET requests), the backing view object definition of ADF REST resources should define access mode set to support paging of the collection in an HTTP Request payload. For more information about range paging, see How to Enable Range Paging for a View Object.

16.3.8 How to Expose Custom Methods in the ADF REST Resource

Custom methods that you expose on the ADF REST resource correspond to custom methods exposed by the client interfaces of the backing view instance of the resource. At runtime, the service client invokes these methods with HTTP POST on the RESTful web service.

In JDeveloper, the overview editor for REST resources displays the list of custom methods in the Custom Methods tab. The list is populated by the methods that have been defined on the view object definition backing the root resource. For example, Figure 16-18 shows the multipleSalary method exposed on the client row interface for the EmployeesView1 view instance.

Figure 16-18 Custom Methods Exposed on the Root of the REST Resource

This image is described in the surrounding text

Before you begin:

It may be helpful to have an understanding of how the ADF REST framework supports application modules and enables service clients to access rows of data and perform service operations. For more information, see About RESTful Web Services and ADF Business Components.

You may also find it helpful to understand other Oracle ADF features that depend on ADF REST resources. For more information, see Additional Functionality for RESTful Web Services.

You will need to complete this task:

To expose custom methods:

  1. In the Applications window, double-click the resource definition file that defines the ADF REST resource you want to edit.
  2. In the overview editor for the REST resource, choose the desired resource from the Resource dropdown and then, in the Structure tree, select the root resource node.

    For more information about Structure nodes, see Table 16-1.

  3. Click the Custom Methods tab of the overview editor, and then, Client Interface section, click Enable for each method that you want to expose. In the Client Row Interface section, click Enable for each row-level method that you want to expose.

    This tab is not displayed for child resource nodes that you select in the Structure tree.

16.4 Versioning the ADF REST Resource

JDeveloper allows you to version the ADF REST resource. It helps create new versions of the ADF REST resource if use cases or backing view objects of ADF REST resource change.

Changes that you make to ADF REST resources during the development cycle can be made without the need to version the resource. However, once you have deployed the RESTful web service, service clients that access the ADF REST resources rely on the stability of the resource collection to satisfy their use cases.

Over time, as use cases change or the backing view objects of the REST resources change, you may need to modify the resource structure of already deployed resources. At that time, modifications to existing ADF REST resources may become backward-incompatible with the deployed REST service and may necessitate creating a new version identifier and ADF REST resource for that version.

16.4.1 How to Version the ADF REST Resource

You use the overview editor for the adf-config.xml file to create new version identifiers and to update the lifecycle status of existing versions. Lifecycle status can be either active, deprecated, or desupported. If the service client requests a resource that does not exist for the requested version, the ADF REST runtime will fallback to a previous version with status active or deprecated

Note that the order of the release name identifiers in the release version list is significant. The ADF REST runtime recognizes the top-most release name as the most recent version. Subsequent release names below the top name in the list form a sequential list of versions. As Figure 16-19 shows, 11.0 is the first version and must appear at the bottom of the list, with subsequent versions, listed above, where 11.2 is the latest version.

Figure 16-19 Managing ADF REST Resource Versions

This image is described in the surrounding text

Note:

To alter the position of a release identifier in the sequential list of versions, you can use the arrows in the Release Versions page of the overview editor to move the identifier up (more recent version) or down (previous version) in the list.

Before you begin:

It may be helpful to have an understanding of how the ADF REST framework supports application modules and enables service clients to access rows of data and perform service operations. For more information, see About RESTful Web Services and ADF Business Components.

You may also find it helpful to understand when editing a resource may introduce backward-incompatible changes that require creating a resource with a new version. For more information, see What You May Need to Know About Versioning ADF REST Resources.

You may also find it helpful to understand how requests by service clients depend on the version identifier of the resource. For more information, see What Happens At Runtime: Invoking ADF REST Resource Versions.

You may also find it helpful to understand other Oracle ADF features that depend on ADF REST resources. For more information, see Additional Functionality for RESTful Web Services.

To manage ADF REST versions:

  1. In the Applications window, in the Application Resources pane, expand the Descriptors and ADF META-INF nodes, and then double-click the adf-config.xml file.
  2. In the overview editor for the adf-config.xml file, click the Release Versions navigation tab, then click the Create New Release Version icon button to create a new resource version identifier.
  3. When you want to change the order of the versions to affect the runtime, select a version from the table and use the arrows to the right of the table to change its hierarchy in the list of versions.

    The ADF REST runtime will recognized the version at the top of the list as the most recent version of the resource.

  4. Optionally, select the status to conform to the desired resource lifecycle: active, desupported, deprecated.

    After you create the version and assign it to REST resources, the version identifier must not be deleted from the adf-config.xml file. The proper way to effectively remove a version is to change its status to desupported.

16.4.2 What You May Need to Know About Versioning ADF REST Resources

The following are examples of changes to the ADF REST resource structure that should be considered backward-incompatible with already deployed RESTful web services:

  • Renaming exposed attributes

  • Removing or hiding previously exposed attributes

  • Removing previously exposed child resources

  • Disabling standard operations or removing custom methods

  • Disabling LOV view accessors or changing an LOV to a different view object

Under certain circumstances, you may modify the ADF REST structure without versioning the resource. The following changes are considered to be backward compatible and therefore do not necessitate creating a new version of the already deployed ADF REST resource.

  • Exposing new attributes and the backing view object does not define the attributes as mandatory

    Note that exposing mandatory-defined attributes requires versioning the resource.

  • Exposing standard operations or exposing new custom methods

  • Exposing new child resources

  • Defining a LOV view accessor for already exposed attributes

16.4.3 What Happens At Runtime: Invoking ADF REST Resource Versions

Version identifiers that you specify will form the URL that the service client uses to invoke operations of the REST resource. For example, the following GET request specifies the URL parameters 11.0 and 11.1 to access two different versions of the Departments resource:

http://localhost:7101/RESTSample_App/rest/11.0/Departments

http://localhost:7101/RESTSample_App/rest/11.1/Departments

When you use the overview editor for the adf-config.xml file to update the lifecycle status of existing versions, you tag each version as either active, deprecated, or desupported. The status deprecated has no runtime impact and is provided for documentation purposes, but the status desupported will cause the deployed resource to become inaccessible.

Note that the order of the release name identifiers in the adf-config.xml file's release version list is significant. The ADF REST runtime recognizes the top-most release name as the most recent version. Release names below the top name in the list form a sequential list of versions. For example, the following GET request specifies the URL parameter latest to retrieve 11.1 of the Departments resource, where 11.1 is at the top of the release versions list:

http://localhost:7101/RESTSample_App/rest/latest/Departments

If the service client requests a resource that does not exist for the requested version, the ADF REST runtime will fallback to a previous version with status active or deprecated. Thus, if the Departments resource versions 11.0 and 11.1 exist but 11.2 does not, the request for version 11.2 will return the next more recent resource, version 11.1.

16.5 Versioning the ADF REST Runtime Framework

JDeveloper allows you to specify the default ADF REST runtime framework that you want the service client to use when processing requests on ADF REST resources. Declaring a default framework version ensures that clients interact with the appropriate level of functionality.

Oracle JDeveloper 12c releases, starting with release 12.2.1.2.0, will introduce ADF REST framework enhancements to support new runtime functionality on service clients. Whether or not your application will benefit from these enhancements depends on the use cases of your application. To support your ability to evaluate framework enhancements before exposing them to service clients, each iteration of the ADF REST framework is identified by a version number, such as version 1, 2, and 3, where version 1 is associated with your application by default. Your application can either remain at the current framework version (for example, the base framework version 1) or you can decide to opt into a newer version (for example, framework version 2) to enhance your application use cases. This ensures that the ADF REST runtime will process the request using the framework version that offers the desired level of functionality for your service clients. Being able to specify a framework version to process requests on your application, allows you to opt into those features when you are ready.

As new ADF REST runtime framework versions are introduced, you may want to update your application to make use of runtime functionality offered in a later framework. To accomplish this, the ADF REST design time allows you to associate a restFrameworkVersion property in the adf-config.xml file to define the default framework version for each version of your application’s ADF REST resources. For example, you may have a resource version 11.0, which is by default associated with the base functionality of framework version 1. Then starting with Oracle JDeveloper 12.2.1.2.0 and ADF REST framework version 2, you can choose to create a new resource version 11.1 and associate it with framework version 2. Alternatively, you can opt into framework version 2 on your existing resource version instead of creating a new resource version. By specifying a default framework version that you associate with individual resource versions, you ensure that your application will expose the appropriate level of functionality to service clients.

Note:

In JDeveloper release 12.2.1.2.0, versions 1, 2, and 3 of the ADF REST runtime framework exist, where version 1 is the base version and includes the ability to support multiple framework versions on the ADF REST service client. For complete details about later versions of the framework (for example, version 2 and version 3), see What You May Need to Know About Versioning the ADF REST Runtime Framework.

16.5.1 How to Version the ADF REST Runtime Framework

You use the overview editor for the adf-config.xml file in Source view to declare the default ADF REST framework versions for the resource versions of the ADF REST application. When the service client requests a resource, the ADF REST runtime will process the request using the declared framework version that is associated with the resource version specified on the request URL.

Before you begin:

It may be helpful to have an understanding of how the ADF REST framework supports application modules and enables service clients to access rows of data and perform service operations. See About RESTful Web Services and ADF Business Components.

You may find it helpful to understand the role of release versions that you create to manage the release iterations of your application’s ADF REST resources. For more information, see Versioning the ADF REST Resource.

You may also find it helpful to understand how an ADF REST framework version may introduce backward-incompatible changes that will require creating a new resource version and declaring a default framework version for it. See What You May Need to Know About Versioning ADF the REST Framework.

You may also find it helpful to understand how the processing of requests by service clients is affected by the ADF REST framework declared for the resource version. See What Happens At Runtime: Invoking an ADF Rest Framework Version.

You may also find it helpful to understand other Oracle ADF features that depend on ADF REST resources. See Additional Functionality for RESTful Web Services.

To declare default ADF REST framework versions:

  1. In the Applications window, in the Application Resources pane, expand the Descriptors and ADF META-INF nodes, and then double-click the adf-config.xml file.
  2. In the overview editor for the adf-config.xml file, click the Release Versions navigation tab to view the existing list of release versions that the application uses.
  3. Optionally, click the Create New Release Version icon button to create a new resource version identifier to associate with the new framework version. For example, you may want to create a new release version when the new ADF REST framework version will introduce backward-incompatible changes to the service client and you wish to preserve the original functionality for the existing release version that you can associate with the existing framework version.
  4. To specify a default framework version to process requests for the resources of a particular release version, click the Source tab and edit the <version> element to add the restFrameworkVersion property with a specific framework version number. In JDeveloper 12.2.1.2.0, version 1, version 2, and version 3 are available. Make no other changes to the XML and specifically do not change the order of the release versions, where the top-most release version defines the most recent release version.
    <versions>
        <version name="11.2" displayName="11.2" restFrameworkVersion="3"/>
        <version name="11.1" displayName="11.1" restFrameworkVersion="2"/>
        <version name="11.0" displayName="11.0" restFrameworkVersion="1"/>
    </versions>
    

    In the above example, requests for ADF REST resources named version 11.0 will use framework version 1 to process the request, while requests for resources named 11.1, will use the functionality offered by framework version 2, and requests for resources named 11.2, will use the functionality offered by framework version 3 when processing the request.

16.5.2 What You May Need to Know About Versioning the ADF REST Framework

One reason that you may want to version the ADF REST framework for your ADF REST application is to opt into new functionality offered by a later version of the ADF REST runtime framework. Currently, Oracle offers three framework versions.

Framework Version 1

The ADF REST runtime framework identified as version 1 was offered starting with JDeveloper release 12.2.1.0.0, when ADF REST was initially introduced. This is the base version which specified a particular JSON payload format. In this release and all subsequent releases, the ability to support multiple framework version was included, by allowing the restFrameworkVersion property in the adf-config.xml file.

Version 1 is the default version that the ADF REST runtime will use to process requests for service clients when no other version is specified. Therefore, when you want to support service clients at the base level of functionality, your application does not need to declare the version using the restFrameworkVersion property in the adf-config.xml file.

Note that the query-by-example resource query syntax supported in the base framework version (version 1) is not compatible with later versions of the ADF REST framework. Beginning with version 2 of the ADF REST framework, a more advanced query syntax is offered instead.

Framework Version 2

The ADF REST runtime framework identified as version 2 was offered starting with JDeveloper release 12.2.1.2.0. The purpose of this new version is to introduce an expanded query expression syntax for ADF REST requests. Version 2 of the ADF REST framework will interpret the q query parameter value differently than the way framework version 1 does, and therefore introduces a backward incompatible change to service clients that rely on framework version 1. Only when framework version 2 (or later) is specified for the resource request will the ADF REST runtime support the use of the expanded expression syntax to process the request.

In version 1, filtering resource collections using the q query parameter is limited to a query-by-example syntax, as follows.

GET /rest/11.0/Departments?q=Dname SA*;Loc BOSTON

Whereas, starting in version 2, the new advanced query syntax supports filtering resource collections using rowmatch query expressions, as follows.

GET /rest/11.1/Departments?q=Dname like 'SA*' or Loc = 'BOSTON'

Note:

To support both rowmatch expressions (offered in framework version 2 and later) and the query-by-example syntax (version 1 only), you would need to associate framework version 2 (or later) with a new release version identifier that you define for the REST resources in the adf-config.xml file. For example, in the above URL samples, you can preserve the original functionality for release version 11.0 and expose the new functionality for version 11.1. This assumes that the adf-config.xml file for the application has declared framework version 2 the default using the restFrameworkVersion=”2” property on release version 11.1. Alternatively, if your service clients will no longer require the functionality of your current framework version, you may associate the new framework version with your existing release version identifier. Therefore, you are not required to increment the release version to make use of a new framework version.

For an explanation of the enhanced query syntax offered by rowmatch expressions, see What You May Need to Know About the Advanced Query Syntax in ADF REST Framework Version 2.

Framework Version 3

The ADF REST runtime framework identified as version 3 was offered starting with JDeveloper release 12.2.1.2.0. The purpose of this version is to add support for retrieving nested child resources with payload attributes that may be used by the service client to determine whether more resource items would be returned in a subsequent ADF REST request. To support this functionality, the payload structure in framework version 3 now represents nested child resources as a resource collection, instead of an array of items, as was true in version 1 and 2. Therefore, version 3 introduces a backward incompatible change to service clients that rely on framework version 1 or version 2. If you decide to opt into version 3, you will expose functionality that allows GET operations to use the ?expand and ?fields query parameter to return a nested child resource as a resource collection with the hasMore attribute. In affect, this change supports pagination of nested child resources that would otherwise require more than one request to fetch.

When you want to add support for framework version 3 to your application, the same guidelines described for framework version 2 (see above section) apply for preserving the existing level of functionality using the restFrameworkVersion property in the adf-config.xml file.

For an example of the new payload structure for nested child resources introduced in version 3, see Fetching Nested Child Resources and Querying With Filtering Attributes (Partial Get). For details about paginating a resource collection using the hasMore attribute, see Paging a Resource Collection.

16.5.3 What You May Need to Know About the Advanced Query Syntax in ADF REST Framework Version 2

The ADF REST runtime framework identified as version 2 was offered starting with JDeveloper release 12.2.1.2.0. The purpose of this framework version is to introduce an expanded query expression syntax for ADF REST requests. This version will interpret the q query parameter value differently than the way framework version 1 does, and therefore introduces a backward incompatible change to service clients that rely on framework version 1.

When you decide to opt into framework version 2 (or later), the ADF REST runtime will process fetch requests for the q query parameter using the expanded expression syntax, whereas requests using the query-by-example syntax will become invalid and will return an error. However, you may decide not to opt into the functionality offered in framework version 2 by leaving the default for your release version set to framework version 1. Or, you may preserve the base functionality by creating a new release version identifier that you associate with framework version 2, while leaving the existing release identifier in the adf-config.xml file as framework version 1.

In version 1, filtering resource collections using query parameters is limited to a query-by-example syntax, which separates expressions using a semi-colon, as follows:

GET /rest/11.0/Departments?q=Dname SA*;Loc BOSTON

Whereas, starting in version 2, a new advanced query syntax supports filtering resource collections using rowmatch expressions, as follows:

GET /rest/11.1/Departments?q=Dname like 'SA*' or Loc = 'BOSTON'

Such rowmatch expressions include the case-sensitive name of a resource item, followed by an operator and one or more operand values (depending on the operator used). The filter can be as simple as a single expression, or it can combine expressions using the and and or conjunctions with matching sets of parentheses for grouping.

Benefits of the Advanced Query Syntax Offered in Framework Version 2 and Later

The advantages of rowmatch expression include the following.

  • They may use supported operators:

    DepartmentNumber = 20

    DepartmentNumber <> 20

    DepartmentNumber <= 20

    DepartmentNumber < 20

    DepartmentNumber >= 20

    DepartmentNumber >20

    DepartmentNumber between 20 and 40

    DepartmentNumber not between 20 and 40

    DepartmentNumber in (20, 30, 40)

    DepartmentName like '%S%'

    DepartmentName like 'RE%'

    DepartmentName not like 'RE%'

    Location is null

    Location is not null

  • They may involve multiple attributes:

    DepartmentNumber = 10 or DepartmentName like 'RESEARCH'

    DepartmentNumber > 10 and DepartmentNumber < 40

    DepartmentNumber < 20 or DepartmentNumber > 30

    (DepartmentNumber = 10 or DepartmentNumber = 30) and (DepartmentName like 'SALES')

    DepartmentNumber BETWEEN 20 and 40) and (Location like 'DAL%')

    (DepartmentNumber > 0 and DepartmentNumber < 100) and (DepartmentName <> 'SALES') and (Location not like 'NEW%')

    (DepartmentNumber = 10 or DepartmentNumber = 30) and (DepartmentName = 'ACCOUNTING' or DepartmentName = 'SALES')

    (DepartmentNumber = 10 and DepartmentName like 'ACC%') or (DepartmentNumber = 20 and DepartmentName like 'RES%')

    DepartmentName='ACCOUNTING' or (DepartmentName like 'R%' and Location like '%ALLA%')

    (DepartmentName like 'R%' and Loc like '%ALLA%') or DepartmentName='ACCOUNTING'

    (DepartmentName like 'R%' or Loc like '%ALLA%') or DepartmentName='ACCOUNTING'

    (DepartmentNumber between 20 and 40) and DepartmentNumber is not null

  • They may involve attributes of nested child resources:

    Deptno > 5 and Emps.Job = 'MANAGER'

    Emps.Job = 'MANAGER' and Deptno > 5

    Deptno > 5 and (Emps.Job = 'MANAGER')

    (Emps.Job = 'MANAGER') and Deptno > 5

    (Deptno > 5) and (Emps.Job = 'MANAGER')

    (Deptno = 10 and Emps.Job = 'PRESIDENT') or (Deptno = 20 and Emps.Job = 'MANAGER')

    Deptno > 5 and Emps.Job = 'MANAGER' and Emps.Sal >= 2500

    Deptno > 5 and (Emps.Job = 'ANALYST' or Emps.Sal >= 4000)

    (Deptno > 5 and Emps.Job = 'ANALYST') or Emps.Sal >= 4000

    Emps.Job = 'ANALYST' or Emps.Job = 'SALESMAN'

    Deptno > 5 and (Emps.Job = 'ANALYST' or Emps.Job = 'SALESMAN')

    Deptno > 5 and Emps.Job = 'MANAGER' and Emps.DirectReports.Sal >= 2000

    Deptno > 5 and (Emps.Job = 'MANAGER' or Emps.DirectReports.Sal >= 2000)

    Deptno > 10 and (Emps.Job = 'MANAGER' and (Loc = 'NEW YORK' or Emps.Mgr=7698))

    Deptno > 10 and (Emps.Job = 'MANAGER' or (Loc = 'NEW YORK' or Emps.Mgr=7698))

    Deptno > 10 and (Emps.Job = 'MANAGER' or (Loc = 'NEW YORK' or Emps.Mgr=7698)) or Deptno = 40

    Deptno > 10 and (Emps.Job = 'MANAGER' or (Loc = 'NEW YORK' or Emps.Mgr=7698)) or (Deptno = 40)

    Deptno > 10 and (Emps.Job = 'MANAGER' or (Emps.DirectReports.Sal > 2000 and (Emps.DirectReports.Comm = 500 or Emps.DirectReports.Deptno > 10)))

    Deptno > 10 and (Emps.Job = 'MANAGER' and (Emps.DirectReports.Sal >= 2000 and (Emps.DirectReports.Comm = 500 or Emps.DirectReports.Deptno > 10)))

  • They may involve the UPPER function:

    UPPER(DepartmentName) = 'RESEARCH'

    UPPER(DepartmentName) = UPPER('research')

    UPPER(DepartmentName) like 'RES%' and UPPER(Location) like 'DAL%'

    UPPER(DepartmentName) like UPPER('research')

Overview of the Advanced Query Syntax Offered in Framework Version 2 and Later

The following are some examples of rowmatch expressions.

  • To test whether a value is null you must use the is null or the is not null keywords:

    AssignedToId is null

    AssignedToId is not null

  • For equality use the = sign, and for inequality use either the != or the <> operators.

    AssignedToId = 100000000089003

    Priority != 1

    Priority <> 1

    ActivityType != 'RS'

    ActivityType <> 'RS'

  • For relational comparisons, use the familiar <, <=, >, or <> operators, along with between or not between.

    Priority <= 2

    Priority < 3

    Priority <> 1

    Priority > 1

    Priority >= 1

    TotalLoggedHours >= 12.75

    Priority between 2 and 4

    Priority not between 2 and 4

  • For string matching, you can use the like operator, employing the percent sign % as the wildcard character to obtain "starts with", "contains", or "ends with" style filtering, depending on where you place your wildcard(s):

    RecordName like 'TT-%'

    RecordName like '%-TT'

    RecordName like '%-TT-%'

  • To test whether a field's value is in a list of possibilities, you can use the in operator:

    ActivityType in ('OC','IC','RS')

  • You can combine expressions using the conjunctions and and or along with matching sets of parentheses for grouping to create more complex filters like:

    (AssignedToId is null) or ( (Priority <= 2) and (RecordName like 'TT-99%'))

    (AssignedToId is not null) and ( (Priority <= 2) or (RecordName like 'TT-99%'))

    When using the between or in clauses, you must surround them by parentheses when you join them with other clauses using and or or conjunctions.

16.5.4 What Happens At Runtime: Invoking an ADF REST Framework Version

After Oracle JDeveloper introduces a new ADF REST framework version (such as framework version 2 offered in JDeveloper release 12.2.1.2.0 and later), you may want to create a new resource version and associate it with the new framework version to ensure that service clients make use of the appropriate level of functionality.

For example, the following URL specifies resource version 11.2, where the application’s adf-config.xml file associates this resource version with version 2 of the ADF REST framework. Because ADF REST framework version 2 supports rowmatch filter expressions, as a result, the ADF REST runtime will process the request with the appropriate functionality and fetch the departments with names that begin with SA (for example, SALES) or have a Location of BOSTON.

http://server/demo/rest/11.2/Departments?q=DepartmentName like 'SA*' or Location = 'BOSTON'

Note that a service client may override the default framework version and process individual requests using a specified framework version that gets passed in a custom header, REST-Framework-Version. In this case, the ADF REST runtime will ignore the application default framework version declaration. If the custom header is omitted on the request, then the ADF REST runtime always uses the application’s default framework version, as defined in the adf-config.xml file. When the application does not define a default framework version and the request on the service client omits the version header, then version 1 of the ADF REST framework is assumed. For information about processing requests using the framework versions, see Working with ADF REST Framework Versions.

The following table contrasts what happens at runtime when a request uses functionality supported (or not supported) by a particular ADF REST framework version. In particular, note the URLs that contrast the query-by-example syntax supported only in version 1 with rowmatch expressions supported in version 2 (and later). The column for the REST-Framework-Version header specifies whether the request passes a version header on the request. When the request includes the version header, the ADF REST runtime processes the request with the passed framework value and overrides the default adf-config.xml file declaration.

Table 16-3 Example Requests Processed By ADF REST Framework Versions

URI REST-Framework-Version Header Resolved Version Success / Error Notes

GET /rest/11.0/Departments

 

1

Success. Uses default framework version for resource version 11.0.

GET /rest/11.1/Departments

1

1

Success. Uses the requested framework version, which matches the default declaration in the adf-config.xml file.

GET /rest/11.0/Departments

2

2

Success. Uses the requested framework version, which overrides the default declaration in the adf-config.xml file.

GET /rest/11.1/Departments

 

2

Success. Uses the default framework version for resource version 11.1.

GET /rest/11.0/Departments?q=Dname SA*;Loc BOSTON

 

1

Success. Uses the default framework version for resource version 11.0, which is defined as version 1.

Query by example syntax is supported in framework version 1.

GET /rest/11.1/Departments?q=Dname SA*;Loc BOSTON

 

2

Error is returned. Uses the default framework version for resource version 11.1, which is defined a version 2.

Query by example syntax is not supported in framework version 2.

GET /rest/11.0/Departments?q=Dname LIKE 'SA*' OR Loc = 'BOSTON'

2

2

Success. Uses the requested framework version, which overrides the default declaration in the adf-config.xml file.

Rowmatch expressions are supported in framework version 2.

GET /rest/11.0/Departments?q=Dname LIKE 'SA*' OR Loc = 'BOSTON'

 

1

Error is returned. Uses the default framework version for resource version 11.1, which is defined as version 1.

Rowmatch expressions are not supported in framework version 1.

GET /rest/11.1/Departments?q=Dname LIKE 'SA*' OR Loc = 'BOSTON'

1

1

Error is returned. Uses the requested framework version, which overrides default declaration in the adf-config.xml file.

Rowmatch expressions are not supported in framework version 1.

16.6 Granting Client Access to the ADF REST Resource

Use the Configure ADF Security wizard and select RESTWebService.jpr as the web project in the wizard to manage ADF REST resource security.

You can enable security for the ADF REST resources when you want to require user authentication to invoke actions on the REST request. Security is handled like all Fusion web applications and is enabled when you run the Configure ADF Security wizard and select the RESTWebService.jpr as the web project in the wizard. Enabling ADF Security on the web service project, means the deployed service will be inaccessible by default and users will require security grants to application roles that confer specific access permission.

Permission that you can grant to users of the RESTful web service is defined by the following classes:

  • oracle.adf.share.security.authorization.RestServicePermission which defines the authorization grants to the standard actions defined in a REST resource.

Table 16-4 lists the actions defined by the ADF REST permission class that you may grant to your defined application roles.

Table 16-4 Secured Actions of ADF REST Resources

Grantable Action Effect on the REST Resource

describe

Grants describing the collections and instances of the REST resource.

get

Grants returning the collection or instance for the REST resource.

update

Grants updating a collection or instance for the REST resource.

delete

Grants deleting a collection or instance for the REST resource.

create

Grants creating a collection or instance for the REST resource.

invoke

Grants invoking custom methods for the REST resource with this grant. Note that the action grants access to all custom methods, but not individual methods.

The general process to authorize users to invoke actions of the ADF REST resource is as follows.

  1. Enable the desired standard actions on the REST resource.

  2. Enable the desired custom methods on the REST resource.

  3. Run the ADF Security wizard on the RESTWebService project.

  4. Create one or more application roles and test users to test security in JDeveloper.

  5. Create a resource grant for the REST resource that you associate with the desired application role.

  6. Map the application roles and their resource grants to your test users.

16.6.1 How to Create a Resource Grant for ADF REST Resources

You can use the overview editor for security policies to create a grant that will secure operations that you have exposed on the resource. JDeveloper will match your resource type definition to the OPSS permission class oracle.adf.share.security.authorization.RestServicePermission, as described in Table 16-4.

Before you begin:

It may be helpful to have an understanding of how the ADF REST framework supports application modules and enables service clients to access rows of data and perform service operations. See About RESTful Web Services and ADF Business Components.

You may also find it helpful to understand other Oracle ADF features that depend on ADF REST resources. For more information, see SeeAdditional Functionality for RESTful Web Services.

You will need to complete these tasks:

To create the ADF REST resource grant:

  1. In the main menu, choose Application and then Secure > Resource Grants.
  2. In the Resource Grants page of the overview editor for security policies, choose ADF REST Resource from the Resource Type dropdown.
  3. Locate the Model project that defines the resource and add it to the Source Project field.
  4. In the Resources column, select the resource.
  5. In the Granted To column, click the Add Grantee icon and choose Add Application Role and then, in the Select Application Roles dialog, click the Add icon and choose the application role to receive the resource grants. For example, if you created a role ManagerRole, select the role and click OK.
  6. With the role selected in the Granted To column, select the desired actions from the Actions list.

    The overview editor displays the resource grant made to the application role, as shown in Figure 16-20.

    Figure 16-20 Creating a Grant for an ADF REST Resource

    This image is described in the surrounding text

16.7 Deploying the ADF REST Resource

You can deploy the RESTful web service to either the Integrated Oracle WebLogic Server of JDeveloper or to the standalone Oracle WebLogic Server.

You can deploy the RESTful web service to either JDeveloper's Integrated WebLogic Server or to standalone Oracle WebLogic Server.

16.7.1 How to Deploy the ADF REST Resource to Integrated WebLogic Server

You can deploy the RESTful web service to JDeveloper's Integrated WebLogic Server using the default Run option that you select on the RESTWebService project, as shown in Figure 16-21.

Figure 16-21 Using the Default Run Option on RESTWebService Project

This image is described in the surrounding text

Once you have deployed the service to Integrated WebLogic Server, you can click the target URL in the Log window to access the service in the HTTP Analyzer tool in JDeveloper and to perform testing using the syntax that establishes the request (GET or POST, for example). For details about testing RESTful web services, see Testing the ADF REST Resources Using Integrated WebLogic Server.

Before you begin:

It may be helpful to have an understanding of how the ADF REST framework supports application modules and enables service clients to access rows of data and perform service operations. For more information, see About RESTful Web Services and ADF Business Components.

You may also find it helpful to understand other Oracle ADF features that depend on ADF REST resources. For more information, see Additional Functionality for RESTful Web Services.

You will need to complete these tasks:

To deploy the web service to Integrated WebLogic Server:

  1. In the Applications window, select the RESTWebService project node, right-click and choose Run.

    If you have not already configured Integrated WebLogic Server, JDeveloper prompts you to configure the default domain.

    JDeveloper deploys the application and starts the web service. During this time, the output from these processes is displayed in the Running: IntegratedWebLogicServer tab of the Log window. After the web service has started, the target URL appears at the bottom of the log, as shown in Figure 16-22.

    Figure 16-22 Log Window Displays Target URL

    This image is described in the surrounding text
  2. After you deploy the web service, in the Running: IntegratedWebLogicServer tab of the Log window, click the target URL to access the web service in the HTTP Analyzer and to perform testing on the deployed service in JDeveloper.

    For example, the Running: IntegratedWebLogicServer tab of the Log window might display the following target URL that you can click, where 7101 is the port number and what follows is the service context root and the REST servlet URL pattern:

    http://<hostname>:7101/RESTSample_App-context-root/rest

  3. Alternatively, to display the web service using a web browser, paste the target URL the Log window into the browser address field, modify the URL to identify the ADF REST resource, and submit the HTTP Get request.

    For example, a Get request for version 11.1 of the Departments resource looks like this:

    http://localhost:7101/RESTSample_App-context-root/rest/11.1/Departments

    Be sure to include the version number that you configured for the resource in the URL. In this example, 11.1 was configured as the version for the Departments resource, as shown in Figure 16-23.

    Figure 16-23 Using the Browser to Make a GET REST Request

    This image is described in the surrounding text

16.7.2 How to Configure the ADF REST Resources Deployment Profile For Standalone Oracle WebLogic Server Deployment

Before you can deploy the RESTful web service to standalone Oracle WebLogic Server, you must configure the ADF REST resources deployment profile to declare the RESTWebService project as a dependent module of the ADF REST application EAR file. This project contains a web.xml file and a weblogic.xml file that ensure access to the REST resources by service clients.

In JDeveloper, you use the Application Assembly page of the Edit EAR Deployment Profile Properties dialog to add the module dependency to the application. Then, when you deploy the ADF REST application, the two files of the selected RESTWebService project will be assembled as a WAR file in the deployed EAR file.

Before you begin:

It may be helpful to have an understanding of how the ADF REST framework supports application modules and enables service clients to access rows of data and perform service operations. For more information, see About RESTful Web Services and ADF Business Components.

You may also find it helpful to understand other Oracle ADF features that depend on ADF REST resources. For more information, see Additional Functionality for RESTful Web Services.

You will need to complete these tasks:

To configure the deployment profile:

  1. Add the RESTWebService project as a dependency for the application's EAR deployment profile:

    1. In the Applications window, select the application and then choose Application - Application Properties from the main menu.

    2. In the Application Properties dialog, choose Deployment and select the application module deployment profile and click Edit Profile.

    3. In the Edit EAR Deployment Profile Properties dialog, choose Application Assembly and expand the RESTWebService.jpr module and then select the project as shown in Figure 16-24 and click OK.

      Figure 16-24 Adding a Deployment Dependency on RESTWebService Project

      This image is described in the surrounding text

16.7.3 How to Deploy the ADF REST Resource to Standalone Oracle WebLogic Server

You can deploy the RESTful web service to standalone Oracle WebLogic Server.

Before you begin:

It may be helpful to have an understanding of how the ADF REST framework supports application modules and enables service clients to access rows of data and perform service operations. For more information, see About RESTful Web Services and ADF Business Components.

You may also find it helpful to understand other Oracle ADF features that depend on ADF REST resources. For more information, see Additional Functionality for RESTful Web Services.

You will need to complete these tasks:

To deploy the web service to standalone Oracle WebLogic Server:

  1. In the Applications window, select the application and then choose Application - Deploy - deployment_profile to server_name from the main menu.

    JDeveloper deploys the application and starts the web service. During this time, the output from these processes is displayed in the Deployment tab of the Log window. After the web service has started, the target URL is also displayed in the Log window.

  2. After you deploying the web service, open the Deployment - Log window and click the target URL to access the web service and to perform testing on the deployed service.

16.7.4 What You May Need to Know About Modifying the Target URL Used by Service Clients

You can edit the REST servlet's URL pattern as you want it to appear in the URL that service clients use to access the service. By default the servlet mapping uses rest in the URL pattern:

http://localhost:7101/RESTSample_App-context-root/rest/11.1/Departments

To edit the servlet mapping pattern, in the Applications window, expand the RESTWebService project and double-click the web.xml file, and then in the editor for the web.xml file, edit the URL pattern for the REST servlet, as shown in Figure 16-25.

Figure 16-25 Editing the URL Pattern for the REST Servlet Mapping

This image is described in the surrounding text

You may also edit the context root as you want it to appear in the URL to access the service. By default, the context root is based on the application name and may be shortened as desired. To edit the context root, in the Applications window, right-click the RESTWebService project and choose Project Properties, and then, in the Project Properties dialog, click Java EE Application and edit the Java EE Context Root as shown in Figure 16-26 and click OK.

Figure 16-26 Editing the Default Context Root on the RESTWebService Project

This image is described in the surrounding text

16.7.5 What You May Need to Know About Deploying ADF REST Resources With MDS Customization Support

If your Model project defines view object shaping definitions and the application supports end user customizations using features of the Oracle Metadata Services (MDS) framework, it is necessary to create a MAR profile that includes the /persdef/ name in the user directory.

This is necessary because MDS customizations define the namespace path shared by the ADF REST shaping definitions:

<namespace path="/persdef/" metadata-store-usage="reposX"/>

In this case, the adf-config.xml file should define deploy-target="true" for the corresponding metadata-store-usage element.

For details about how to package the customized metadata, see How to Package and Deploy Customized Applications.

16.8 Testing the ADF REST Resources Using Integrated WebLogic Server

JDeveloper allows you to test an ADF REST resource deployed on the Integrated WebLogic Server. Use the HTTP Analyzer to create an HTTP request, web browser for GET requests, or cURL command line tool.

You use JDeveloper to deploy the RESTful web service to Integrated WebLogic Server and then access the ADF REST resources using the target URL generated by the deployment process. Using the generated URL, you can make requests to test the ADF REST resources of the ADF Model project.

You can use any of the following techniques to test the deployed RESTful web service by modifying the URL of the deployed service to return an expected payload:

  • In the HTTP Analyzer in JDeveloper, using the Create HTTP Request option

  • In a web browser (typically limited to GET requests)

  • In the cURL command line tool from a command window

    Note that cURL is a third-party tool that you can install and configure to make REST requests using a command window.

Testing the ADF resource using the deployed RESTful web service requires knowledge of the REST API syntax enabled by the ADF REST runtime. However, you can use the instructions in this document to make a basic GET request to view a resource collection.

For example, a GET request that returns all versions of all resources looks like this:

http://<server>/<context-root>/rest

For example, a GET request that returns all resources of a specific version looks like this:

http://<server>/<context-root>/rest/<versionID>/describe

For example, a GET request that returns a specific version of a specific resource collection looks like this:

http://<server>/<context-root>/rest/<versionID>/<resourceName>

Before you begin:

It may be helpful to have an understanding of how the ADF REST framework supports application modules and enables service clients to access rows of data and perform service operations. See About RESTful Web Services and ADF Business Components.

You may also find it helpful to understand the ADF REST framework and the syntax for making API calls using HTTP methods. See Consuming RESTful Web Services Using the ADF REST Framework.

You may also find it helpful to understand other Oracle ADF features that depend on ADF REST resources. See Additional Functionality for RESTful Web Services.

You will need to complete these tasks:

To test the web service using HTTP GET:

  1. To test using JDeveloper's HTTP Analyzer, choose Tools - HTTP Analyzer from the main menu, then choose Create New HTTP Request in the HTTP Analyzer Log window and then, in the HTTP Analyzer, select the HTTP Content tab and paste the target URL that you copied from the Log window into the URL field, modify the URL to identify the REST resource, then choose the desired Method and click Send Request.

    Be sure to include the version number that you configured for the resource in the URL. In this example, 11.1 is the release name version identifier used to access the Departments resource, as shown in Figure 16-27.

    Figure 16-27 Using the HTTP Analyzer to Make a GET REST Request

    This image is described in the surrounding text

    Note that the HTTP Analyzer supports SOAP, standard HTTP, and REST type requests. However, the WADL that you might normally supply to the HTTP Analyzer to define a generic RESTful web service does not support the describe format of ADF REST resources. Therefore when using the HTTP Analyzer to test the deployed ADF REST resource, you must create a new HTTP type request instead of a REST request.

  2. To test using the third-party cURL command line tool, open a command prompt and enter a cURL command for the REST resource similar to the following, where -v is the option to see what cURL sends and -X is the request option:

    curl -v -X GET http://127.0.0.1:7101/RESTDemo/rest/11.1/Departments

    Be sure to include the version number that you configured for the resource in the URL. In this example, 11.1 is the release name version identifier used to access the Departments resource, as shown in Figure 16-28.

    Figure 16-28 Using cURL to Make a REST Request

    This image is described in the surrounding text