Creating OpenEdge REST Web Services : Data Object Services : Overview of Data Object Services
Overview of Data Object Services
An OpenEdge Data Object implements a single server-side resource that provides client access to a set of OpenEdge data and operations through the agency of a Data Object Service, which is a type of REST Web service with additional information about the data and operations that a client can access. You implement a Data Object resource using an OpenEdge Business Entity (the Data Object), which is typically an annotated ABL user-defined class that provides access to resource data and business logic through public methods that implement the resource operations. You can also implement a Business Entity as a persistent procedure (procedure object), with resource operations implemented as internal procedures. However, OpenEdge tools that help you create new Business Entities always create ABL classes to implement Data Objects.
A Business Entity can provide a standard set of operations to access a single data model—either a single temp-table or a single ProDataSet resource with one or more temp-tables—and can also provide access to custom ABL business logic as well. The operations that a Business Entity can implement include:
Read — A standard operation that returns any number of records to the client according to optional server pre-processing that can include filtering of the result set, sorting of the result set, and paging of the result set (returning a fixed batch of records from the result set upon request).
Create, Update, or Delete (CUD) — A set of standard operations that create, update, or delete (respectively) a single record per network request.
Submit — A standard operation that can create, update, and delete multiple records per network request, providing support for complex data transactions.
Invoke — A custom operation that can execute any method in the Business Entity other than the methods used to implement standard operations.
A Business Entity class must provide a separate and distinct method, with a particular signature and annotations, to implement each of the five standard CRUD and Submit operations supported by a given Data Object resource. The same Business Entity can also provide one or more methods that are annotated as custom Invoke operations, where each method can have any supported ABL signature (see Coding ABL for Data Object operations).
When a Data Object is first accessed by a client, its Business Entity is instantiated on an OpenEdge application server as a singleton class, where it can be accessed by all clients that need this Data Object resource from a given Data Object Service.
The main difference between an OpenEdge REST Service providing access to REST resources and a Data Object Service is that a Data Object Service has information that allows clients to access the data and operations of Data Object resources without having to construct the corresponding calls to REST resources. Instead, the client accesses methods of a single client-side Data Object that hides all the details of the REST resources supported by a single corresponding server-side Data Object.
Thus, an OpenEdge Data Object Service is a combination of an OpenEdge REST Web service and a Data Service Catalog that defines how clients can access server-side Data Object resources using corresponding client-side Data Objects. This Data Service Catalog is a JSON file that defines the schema of the data and the operations on the data that are supported by each Data Object resource provided by a given Data Object Service. Instead of only defining a RESTful mapping of HTTP verbs to Web URIs and header data on which these verbs operate (resulting in a mapped RPC), a Data Service Catalog defines these same REST resources as implementations for methods of a client-side Data Object. These client-side Data Object methods are there by defined to correspond to methods of a correspondingg server-side Data Object based on annotations in its implementing ABL Business Entity (resulting in an annotated RPC).
As a result, a client can access the data and operations of a server-side Data Object simply by calling the corresponding methods of the client-side Data Object in exactly the same way that it calls any object methods in the client's implementation language, and without having to code the HTTP verbs, URIs, and header information for REST requests. These client-side Data Objects also afford the client access to data processing features that mirror the capabilities of OpenEdge server-side Data Objects, such as before-imaging and the multi-table data modeling provided by OpenEdge ProDataSets, which allow the client to participate in complex transaction processing.
A given OpenEdge Data Object Service can support any number of Data Object resources as defined by its Data Service Catalog, which is generated by OpenEdge when you create the Data Object Service. You can then deploy the Data Object Service in a Web application, just like any OpenEdge REST Web service, but with the addition of its Catalog, which is deployed as a static file in the Web application.
Progress currently supports the instantiation of client-side Data Objects for JavaScript clients as part of a Cloud Data Object open source project on GitHub. Using the supported Progress Data Object libraries from this project, together with access to available OpenEdge Data Object Services and their Catalogs, a mobile or Web app developer can create instances of a JavaScript Data Object (JSDO), the client-side Data Objects, that provide access to corresponding OpenEdge Data Object resources on the server.
For more information on using client-side Data Objects to access server-side Data Objects, see the documentation on Progress Data Objects in the Cloud Data Object project on GitHub: http://clouddataobject.github.io/, or directly access the Progress Data Objects Guide and Reference: https://documentation.progress.com/output/pdo/.
OpenEdge supports the development and deployment of Data Object Services for both the Progress Application Server for OpenEdge (PAS for OpenEdge), where Data Object Services are deployed directly to the PAS for OpenEdge, and the classic OpenEdge AppServer, where Data Object Services can be deployed to any generic Tomcat Web server that supports OpenEdge REST applications. Progress Developer Studio for OpenEdge provides wizards and other tools to accelerate the development of OpenEdge Data Objects and Services for both application server environments. This support includes wizards that provide automatic (default) or custom annotations to Business Entity methods that implement Data Object operations.
Progress Developer Studio for OpenEdge supports Data Object development for each of the two OpenEdge application servers (PAS for OpenEdge or the classic OpenEdge AppServer) using different and distinct types of OpenEdge Server projects. To develop Data Objects for deployment to PAS for OpenEdge with the corresponding ABL Business Entities running on PAS for OpenEdge, you must use a PAS for OpenEdge Server project to create and manage a Data Object Service with either a REST transport using a REST RPC service provider or a WEB transport using a WebSpeed (WebHandler) service provider. To develop Data Objects for deployment to a generic Tomcat Web server with the corresponding ABL Business Entities running on the classic OpenEdge AppServer, you must create a Classic Server project, which only supports Data Object Service development using the classic AppServer implementation. (An OpenEdge Server project can similarly be used to develop REST and APSV (ABL application) services on either PAS for OpenEdge and the OpenEdge AppServer.)
Note that the WebHandler service provider imposes the following limitations on the coding for any Business Entity (or other service interface) used to implement a resource for the Data Object Service:
No current support for ABL procedures as Business Entities — You can only code user-defined ABL classes as Business Entities for access by the WebHandler. As a workaround, you can call into any procedure (.p) that was previously used as a resource service interface from the ABL class.
No support for DEFINE TEMP-TABLE x LIKE y — A Business Entity (or other service interface) for access by the WebHandler cannot contain a temp-table definition as part of its schema that includes the LIKE option. For example:
DEFINE TEMP-TABLE ttCustomer LIKE Customer.
If any Business Entity is a resource of a Data Object Service defined using the WebHandler, and it contains a TEMP-TABLE statement with LIKE as part of its schema, the Read operation on that Business Entity fails and returns an error to any client app as a result.
For more information, see the topics on Data Objects and Data Object Services in the Developer Studio online help Progress Developer Studio for OpenEdge Guide.
Note: The generated files for a Data Object Service created with the WebHandler service provider include a ServiceName.json Catalog file located in PASforOEInstance\webapps\WebApplicationName\static, exactly the same as for a REST RPC service provider. The only difference is in the relative transport URI specified in URIs for client apps to access resource operations. For more information, see Data Object URIs for testing resources from REST clients.
Note: For the WebHandler service provider, an OpenEdge ServiceName.gen file is generated in PASforOEInstance\webapps\WebApplicationName\WEB-INF\openedge, instead of the ServiceName.paar file generated for REST RPC. This ServiceName.gen file is similar in function to the REST RPC ServiceName.paar file. However, ServiceName.gen is a readable JSON file containing the same mapping information required to map request and response messages to Data Object Service resource operations.
Read — A standard operation that returns any number of records to the client according to optional server pre-processing that can include filtering of the result set, sorting of the result set, and paging of the result set (returning a fixed batch of records from the result set upon request).