Data service layer
The data service layer (DSL) provides an abstraction layer for data access that is independent of the physical schema.
The purpose of the data service layer is to provide a consistent interface (called the data service facade) for accessing data, independent of the object-relational mapping framework (such as EJB, DAS, or JPA). In its turn, the abstracted mapping framework is used to transform the data retrieved from the database into a collection of Java objects. These objects are implemented as physical service data objects (SDOs).
The data service layer performs bidirectional transformations between physical SDOs and logical SDOs. It allows you to perform create, retrieve, update, and delete operations on the logical SDOs. Alternately, the data service layer also lets you do create, retrieve, update, and delete operations directly on the physical data, bypassing the logical schema altogether.
XPath is used as a query language on the logical schema. The data service layer maps XPath queries to templates of SQL statements. These templates are used to generate actual SQL statements that access the database.
The data service layer also allows the templates to contain business context variables, which get substituted when the SQL statements are generated. Thus, the XPath queries sent in by the client can result in different actual SQL queries, depending on the property values of the business context. The statements are stored in a separate query template file, which isolates the runtime logic from the SQL query code.
The query template file provides a mechanism to easily map from the query on your logical model, your XPath query, to one or more SQL statements. These statements retrieve the physical data from the database.
The file also isolates the SQL statements from the runtime Java code, which makes the code easier to maintain. It is also useful to database administrators when they want to locate and analyze queries. Changes to the SQL queries do not require Java recompilation.
The following diagram shows the different layers of the HCL Commerce programming model and how the data service layer fits into the model:
DSL consists of three pieces: the business object mediation service, the physical persistence service, and the data service facade.
The business object mediation service initializes mediators. These are classes that transform between the logical and physical representations of the domain model. This allows the business logic layer to deal only with the logical representation of the data.
Each service module provides its own mediators, and there are two kinds: Read and Change mediators. They are listed in the BOM configuration file. Read mediators are used to process the OAGIS Get requests. Change mediators handle the OAGIS Change, Process, and Sync requests.
The mediators access the physical data through the physical persistence service. This service translates XPath queries to SQL queries.
The Data Service Facade is a thin layer that provides a single entry point into DSL. It provides interfaces to work with both physical and logical data, and it delegates to the business object mediation service or to the physical persistence service. It also allows each service module to register with the data service layer, and loads the service module-specific configuration files.
For read operations, the data service layer facade receives a query from the business logic layer. The query consists of an XPath expression and an access profile, which are extracted from the OAGIS GET verb. The data service layer forwards this query to the business object mediator (BOM) who, in turn, passes it to the persistence service. That service looks up the correct SQL template for the query, and uses it to generate one or more SQL statements. It then runs these statements, and maps their result sets into physical SDOs. This mapping, between the database schema (tables and columns) and the SDO classes, is defined by XML called Object-relational metadata. Finally, the physical SDOs are returned to the BOM. The BOM configuration describes how to instantiate the necessary mediators. These are returned to the business logic layer. It is the mediator that is returned, not just the SDO. The mediator contains the physical SDO data. It also contains the logic to convert the physical SDO to the logical SDO (which is the Java representation of an OAGIS noun).
For change operations (create, update, delete), the data service layer facade receives the OAGIS nouns as input, and passes them to the business object mediation service. This service instantiates the appropriate change mediators. In turn, they fetch the physical representation of the nouns from a service called the physical object mediation service. The BOM then returns the mediators to the business logic layer. The mediators are then called with specific actions to create, update, or delete nouns and noun parts. The logic inside the mediators translates these actions into operations on physical SDOs. For example, a create request creates physical objects and populate them with noun values. After making all its changes, the business logic layer instructs the change noun mediator to save the updated physical SDOs. The mediator calls a physical object persistence service to update the database.
Data service layer limitations
- All tables must have a primary key.
- Multi-column primary keys are not supported for base tables.
- The default graph composer is only able to merge the result sets of the association SQL statements if these result sets do not fetch identical records from tables other than the base table.
- When you use a two-step process to locate the objects by primary keys and then retrieve all the data given those primary keys, it is not always possible to sort the results of the final query. You cannot order the result of the XPath to SQL query and then propagate the ordering to the result of the association SQL query. If ordering of the result is necessary, it is recommended to use a single-step query. An order by statement is required when ordering sub noun pagination when only one association SQL is being used with an XPath to SQL statement.
- The pagination parameters are always required for the sub noun-level pagination service. The pagination parameters are optional for the noun-level pagination service.
- Extensions to SOI service modules (modules using name-value pair commands) should not use the data service layer.
- Extension to BOD service modules must exclusively use the data service layer.
- Parametric search queries must use two-step queries (locate the objects by primary keys and then retrieve all the data given those primary keys).
- You should not be using the EJB and data service layer persistence models in the same transaction.
- You should never read or update the same data using the JDBCQueryService and the PhysicalDataContainer within the same transaction. If you do, there is a chance that you can read stale data or end up with corrupted data in the database.