Skip navigation.
Downloads | Product Documentation | Support

Client Application Developer's Guide

# Introducing Data Services Platform for Client Application Developers

BEA AquaLogic Data Services Platform (DSP) brings a service-oriented architecture (SOA) approach to data access. Data Services Platform enables organizations to consolidate, integrate, and transform as needed disparate data sources scattered throughout their enterprise, making enterprise data available as an easy-to-access, reusable commodity: a data service.

For client application developers, DSP provides a uniform, consolidated interface for accessing and updating the heterogeneous back-end data sources that comprise data services. This chapter provides an overview of Data Services Platform for client application developers. It includes the following topics:

- Simplifying Application Data Programming
- The Role of WebLogic Server and WebLogic Workshop
- Introducing Service Data Objects (SDO)
- Typical Client Application Development Process
- Additional Technical and Product Information

Note: Data Services Platform was initially named Liquid Data. Some artifacts of the original name remain in the product, installation path, and components.

# Simplifying Application Data Programming

The Data Services Platform (DSP) significantly simplifies how client applications access and use data. In a typical organization, data comes from a variety of sources, including distributed databases, files, applications from partners or e-commerce exchange markets. With DSP, client applications can use heterogeneous data through a unified service layer without having to contend with the complexity of working with distributed data sources using various connection mechanisms and data formats.

DSP provides a uniform, consolidated interface for accessing and updating heterogeneous back-end data. It enables a services-oriented approach to information access using data services.

From the perspective of a client application, a data service typically represents a distinct business entity, such as a customer or order. Behind the scenes, the data service may aggregate the data that comprises a single view of the data, for example, from multiple sources and transform it in a number of ways. A data service may be related to other data services, and it is easy to follow these relationships in DSP. Data services insulate the client application from the details of the composition of each business entity. The client application only has to know the public interface of the data service.

This document describes how to create DSP-aware client applications. It explains the various client access mechanisms that DSP supports and its main client-side data programming model, including Service Data Objects (SDO). It also describes how to create update-capable data services using the DSP update framework.

This guide provides information about how to leverage data services in your applications. For information about creating data services in WebLogic Workshop, see the Data Services Developer's Guide.

## What is a Data Services Platform Client?

In the typical organization, data flows in a bidirectional manner from a wide variety of sources, including distributed databases, various files, applications from partners, or e-commerce exchange markets.

Creating an application that can access and update distributed, disparate data sources can be complex, challenging, and expensive: you must know how to use a wide variety of connection mechanisms and data formats, and how to use the variety of APIs required to access and update each back-end data source, for example.

Using DSP, data architects create data services that:

- Insulates applications from having to access and update multiple disparate data sources.
- Provides the ability to create data services that combine elements of multiple, disparate data sources into, essentially, virtual databases.

### Data Your Way

A DSP client is any process that consumes data services. A client application may be, for example, a Java program, non-Java programs such as .NET applications, BEA WebLogic Workshop applications, or JDBC/ODBC clients.

For client application developers needing to leverage such data assets, DSP supports multiple access methods (see Figure 1-1):

- Java clients can use data service functions through the DSP Mediator API.
- Workshop applications (such as portals, business processes, and web applications) can use a Data Service control.
- Web services enable you to make DSP services available to a wide array of WebLogic and non-WebLogic applications and integration channels.
- The DSP JDBC driver provides JDBC and ODBC clients, such as reporting tools, with SQL-based access to DSP information.

Figure 1-1 Accessing DSP Services

Whatever the client type, DSP gives application developers a uniform, services-oriented mechanism for accessing and modifying heterogeneous data from external sources. Developers can focus on the business logic of the application rather than details of various data source connections and formats.

## The Role of WebLogic Server and WebLogic Workshop

Data services are created in WebLogic Workshop, BEA's integrated development environment for building and deploying many types of applications: portals, Web services, and integration applications, for example. The Data Services Platform application running under Workshop supports all aspects of Data Services Platform creation.

### What is a Data Service?

From a high-level perspective, a data service defines a distinct business entity such as a report that describes a customer and customer orders. The data service defines a unified view by aggregating data from any number of sources — relational database management systems (RDBMS), Web services, enterprise applications, flat files, and XML files, for example. Data services can also transform data from the original sources as needed.

In order to use data services, you need know only a few details, such as:

- The name of the data service.
- The functions and procedures exposed by the data service. (See What is a Data Services Platform Client Application?)
- The data types available.

Data service client applications can use data services in the same way that a Web service's client application invokes the operations of a Web service. Rather than invoking operations from a Java client application, the data service client application invokes a data service routine.

Figure 1-2 Data Services Layer Exposes Functions and Procedures to Client Application Developers

Note: For complete information on creating data services see the DSP Data Services Developer's Guide.

### What is a Data Services Platform Client Application?

A DSP client application is any application that invokes data service routines. Client applications can include Java programs, non-Java programs such as Microsoft ADO.NET applications, BEA WebLogic Workshop applications, or JDBC/ODBC clients:

- Java client applications can use data service functions and procedures through the Data Services Mediator API (also known simply as the Mediator API).
- WebLogic Workshop applications (such as portals, business processes, and Web applications) can leverage data services by means of Data Service controls. (Controls are reusable Java components that can be used in WebLogic Workshop applications.) Data Service controls can be used as the basis of many DSP-enabled application scenarios. For example:

- Data Service controls can be added to Web services, portal projects, and Web projects.
- Data Service controls can be used to generate Web services that can make DSP services available to a wide variety of WebLogic and non-WebLogic applications and integration channels.
- Data Service controls can be used within a JPD (Java process definition, a workflow component).

- The DSP JDBC driver provides JDBC and ODBC clients, such as reporting tools, with SQL-based access to DSP data.

Regardless of the client type, DSP provides a uniform, services-oriented mechanism for accessing and modifying distributed, heterogeneous data. Developers can focus on business logic, rather than on the details of various data source connections and formats.

In your client application code, simply invoke the data service routine: the DSP engine:

- Gathers data from the appropriate sources (via XQuery)
- Instantiating results as data objects, and
- Returns to your client application the materialized data objects.

These data objects conform to the Service Data Object (SDO) specification, a Java-based architecture and API for data programming that is the result of joint effort by BEA and IBM.

### Security Considerations in Client Applications

Data Services Platform administrators can control access to deployed DSP resources through role-based security policies. DSP leverages and extends the security features of the underlying WebLogic platform. Roles can be set up in the WebLogic Administration Console. (Refer to the DSP Administration Guide for information about the DSP Console.)

Access policies for DSP resources can be defined at any level — on all data services in a deployment, individual data services, individual data service functions, or even on individual elements returned by the functions of a data service.

For complete information on WebLogic security, see:

`http://e-docs.bea.com/wls/docs81/security/index.html`

# Choosing a Data Services Programming Model

Application developers can choose from several models for accessing DSP services. The model chosen will depend on the access mechanism you decide to used. The possible access methods are:

- Data Mediator API
- Data service control
- Web Services
- JDBC/ODBC

Each access method has its own advantages and use. Table 1-3 provides a description of each of these access methods and summarizes the advantages of the various models for accessing DSP services.

Table 1-3 Data Services Platform Access Models

Access mechanism | Description | Advantages/When to use...
--- | --- | ---
Data Service Mediator API | A Java interface for using data services. Returns data as data objects, providing full support for Service Data Objects (SDO) programming. For more information, see DSP's Data Programming Model and Update Framework. | Can be developed with standard Java IDEs such as BEA WebLogic Workshop, Eclipse, IntelliJ, JBuilder, and others. Easy-to-use approach to developing Java programs that use external data. Provides several access modes, including a dynamic (untyped) interface through generic SDO, a static (typed) interface, and an ad hoc query interface. Seamless ability to submit data changes.
Data Service Control | A Java control extension (JCX) file for accessing DSP resources. For more information, see Accessing Data Services from WebLogic Workshop Applications. | Best suited for BEA WebLogic Workshop applications, including portals, business process workflows, and pageflows. Leverages BEA WebLogic Workshop features for working with controls, such as drag-and-drop method and variable generation. Provides an ad hoc query interface for a highly dynamic approach to querying information. Seamless ability to submit data changes.
Web Service | A data service can be wrapped as a Web service, providing the data service with the benefits of web service features. For more information, see Web Services and DSP-Enabled Applications. | Makes standard Web service features available to data services, such as WS-Security, WSDL descriptors, and more. Makes data services usable from .NET applications, or other non-Java programs. Ideal for XML-based SOA architectures
JDBC/ODBC | Client applications can use JDBC or ODBC to access DSP services using SQL queries. The DSP JDBC driver supports SQL-92. For more information, see Using the Data Services Platform JDBC Driver. | Works with applications designed for JDBC access, such as Cognos business intelligence software and Crystal Reports. Enables users to leverage existing SQL skills and resources. Limited to flat views of data.

# Introducing Service Data Objects (SDO)

Service Data Objects (SDO), a specification proposed jointly by BEA and IBM, is a Java-based architecture and API for data programming. SDO unifies data programming against heterogeneous data sources. It simplifies data access, giving data consumers a consistent, uniform approach to using data whether it comes from a database, web service, application, or any other system.

SDO uses the concept of disconnected data graphs. Under this architecture, a client gets a copy of externally persisted data in a data graph, which is a structure for holding data objects. The client operates on the data remotely; that is, disconnected from the data source. If data changes need to be saved to the data source, a connection to the source is re-acquired. Keeping connections active for the minimum time possible maximizes scalability and performance of applications.

To SDO clients, the data has a uniform appearance no matter where it came from or what its source format is. Enabling this unified view of data in the SDO model is the Data Service Mediator. The mediator is the intermediary between data clients and back-end systems. It allows clients to access data services and invoke their functions to acquire data or submit data changes. DSP serves as such a SDO mediator.

On the client side, information takes the form of data objects. Data objects are the basic unit of information prescribed by the SDO architecture. SDO has both static (typed) and dynamic (untyped) interfaces for working with data objects.

Static interfaces provide a programmer-friendly model for getting and setting properties in a data object. Accessors are generated for each property in the data type of a data service, for example getCustomerName( ) and setCustomerName( ) for a Customer data object. Static interfaces depend on a schema for type information.

The dynamic interface, on the other hand, is useful when a type is unknown or undefined at runtime. Dynamic interface calls are in such forms as:

>     get("CustomerName")

>     set("CustomerName", "J. Dough").

In keeping with the goals of a service-oriented architecture (SOA), data graphs are self-describing. The metadata API enables applications, tools, and frameworks to inspect information on the data contained in a data graph. The data is described by an XML schema, which describes the names of properties, their types, and more.

For details on using SDO, see DSP's Data Programming Model and Update Framework.

## Update Frameworks and the Data Service Mediator

The SDO specification does not specify an update framework, but it does discuss the need for mediator services, in general, to handle updates to data objects; the SDO specification leaves the details up to implementors.

The SDO specification allows for many types of mediators, each intended for a particular type of query language or back-end system. DSP provides a Data Service Mediator, a server-side component of DSP's XQuery processing engine that serves as the intermediary between data services and client applications or processes.

The Data Service Mediator facilitates updates to the various data sources that comprise any data service. DSP's Mediator service is the core mechanism for the DSP update framework. The Mediator handles updates to relational and non-relational data sources as follows:

- Relational data sources. Relational database management systems (RDBMS), such as IBM, Oracle, Microsoft SQL Server, and any other SQL-92 compliant RDBMS. For relational data sources, DSP propagates changes to relational data sources automatically. See The Data Services Platform Update Framework for an overview of default behavior. (However, note that you can override the default update processing for a relational source if you like, or when necessary. See When Are Update Overrides Required for Relational Data Sources? for more information.)
- Non-relational data sources. This included non-relational data sources, such as Web services, XML files, and flat files. Updates to non-relational data sources always require custom server-side coding; specifically, an update override class. See Developing the UpdateOverride Class for information about how to create a Java class to customize server-side behavior.

# Typical Client Application Development Process

Developing client applications that invoke Data Services Platform functions and procedures presumes that a DSP project has been deployed or is being deployed. See the Data Services Developer's Guide for detailed information about developing data services.

Developing a DSP-enabled client applications encompasses these steps:

1. Identify the data services you want to use in your application. The Data Services Platform Console can be used to find all services available on your WebLogic Server. The DSP Console serves as a data service registry within the DSP architecture; it shows available data services, including the specific functions and procedures that each data service provides.
2. Choose the data access approach that best suits your needs. (Table 1-3 describes the advantages of the different access mechanisms.) The approach you choose also depends on precisely how the data service has been deployed.

For example, if the data service is hosted as a Web service, you can develop a Web service client application using Java in conjunction with the service's WSDL file.

Similarly, if the data service is incorporated in a portal, business process, or Web application, your client application development process may take place entirely in the context of the server, as a set of pageflows or other server-side artifacts.

3. Obtain the required JAR files (see Table 1-5). To use the typed data service and SDO interfaces, obtain the DSP application's generated Mediator client JAR file from your DSP administrator or data architect. Or generate the file yourself by following the steps outlined in Generating a Static Mediator API JAR File.

Figure 1-4 provides a conceptual overview of the various approaches, highlighting some of the relationships among various sub-systems and components.

Figure 1-4 Types of Data Services Platform Client Applications

## Development Resources

Client application developers typically work with a small set of APIs, contained in JAR files. The APIs are primarily described through Javadocs (see DSP Mediator API Javadoc on page 1-13).

### Runtime Client JAR Files

Data Services Platform APIs are contained the packages listed in Table 1-5.

Table 1-5 Data Services Platform Java Archive Files

Name | Description | Location
--- | --- | ---
[`App`]`-ld-client.jar` | Contains generated typed interfaces for data services and their data types (static data APIs). The name of the file is is prefixed by the name of the DSP application from which the static interfaces are generated. Such an application-specific JAR file is not required if the only interface to Data Services Platform routines is through an untyped interface using generic SDO. | (Provided by your Data Services Platform administrator.)
`ld-client.jar` | The dynamic, or untyped, data service APIs, including generic data service interfaces and ad hoc query interfaces. | <bea_home>`\weblogic81\liquiddata\lib\`
`wlsdo.jar` | The interfaces defined in the SDO specification, including untyped data interfaces and data graph interfaces. | <bea_home>`\weblogic81\liquiddata\lib\`
`weblogic.jar` | The common WebLogic APIs. | <bea_home>`\weblogic81\server\lib\`
`xbean.jar` `xqrl.jar wlxbean.jar` | XMLBean classes and interfaces on which the Data Services Platform SDO implementation relies. Also enables XPath expressions in untyped data accessors. 1 | <bea_home>`\weblogic81\server\lib\`

1. A "query too complex" exception is raised if the `xqrl.jar` and `wlxbean.jar` files are not in the JVM's CLASSPATH when an XPath expression is executed. If you encounter this error, make sure that these two JAR files are in the CLASSPATH.

### DSP Mediator API Javadoc

The Data Services Platform Mediator API describes the routines needed by DSP client applications to invoke various DSP routines.

Client application developers will find Javadoc helpful for creating client applications that invoke data service routines. Data services developers and architects will find the Javadoc useful for understanding how to customize update behavior.

You can find javadoc for the Data Services Platform 2.1 Mediator API at:

>     http://e-docs.bea.com/aldsp/docs21/javadoc/index.html

Client applications built on earlier versions of Data Services Platform can continue to use the 2.0.1 mediator API routines. These are described in a Javadoc named javadoc-dsp201 and is available at:

>     http://e-docs.bea.com/aldsp/docs21/javadoc-dsp201/index.html

Javadoc is also provided in ZIP file format; it is available for download from the DSP e-docs Web site:

>     http://e-docs.bea.com/aldsp/docs21/index.html

## Performance Considerations

Data service performance is the result of the end-to-end components that make up the entire system, including:

- Data service design. The number of data sources, complexity of logical data source consolidation, and other data service design considerations can affect performance.
- Number of clients accessing the data service. Number of simultaneous clients can affect performance.
- Performance of the underlying data sources. When data services access underlying data the availability and availability and performance of those systems can affect performance.
- Network topology. Overall available bandwidth must be measured against the number of applications running on the WebLogic Server, number of other applications in general consuming network bandwidth (can affect client response times).
- Hardware resources. The number of CPUs, processing power, memory allocation, and other factors for each and every platform throughout the system, client and server alike, can affect performance.

Before creating a client application for a data service, it is recommended that you benchmark performance of each underlying data source, and then benchmark the performance of the data service as you develop it. Use load-testing tools to determine the maximum number of clients that your data service can support.

In addition, you can use DSP's auditing capabilities to instrument your code, thereby gaining performance profile information that you can use to identify and resolve performance problems if they occur. For detailed information on DSP audit capabilities see DSP Administration Guide.

# Additional Technical and Product Information

A compendium of technical and product information related to BEA AquaLogic Data Services Platform can be found in the introductory chapter of the DSP Concepts Guide.