> Samples Tutorial > Consuming Data Services Using Java

Samples Tutorial

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Consuming Data Services Using Java

After a Data Services Platform (ALDSP) application is deployed to a WebLogic Server, clients can use it to access real-time data. ALDSP supports a services-oriented approach to data access, using several technologies:

In this lesson, you will enable ALDSP to consume data through the SDO Mediator API.

 

Objectives

After completing this lesson, you will be able to:

 

Overview

SDO is a joint specification of BEA and IBM that defines a Java-based programming architecture and API for data access. A central goal of SDO is to provide client applications with a unified interface for accessing and updating data, regardless of its physical source or format.

SDO has similarities with other data access technologies, such as JDBC, Java Data Objects (JDO), and XMLBeans. However, what distinguishes SDO from other technologies is that SDO gives applications both static programming and a dynamic API for accessing data, along with a disconnected model for accessing externally persisted data. Disconnected data access means that when ALDSP gets data from a source, such as a database, it opens a connection to the source only long enough to retrieve the data. The connection is closed while the client operates on the data locally. When the client submits changes to apply to the source, the connection is reopened.

ALDSP implements the SDO specification as its client programming model. In concrete terms, this means that when a client application invokes a read function on a data service residing on a server, any data is returned as a data object. A data object is a fundamental component of the SDO programming model. It represents a unit of structured information, with static and dynamic interfaces for getting and setting its properties.

In addition to static calls, SDO, like RowSets in JDBC, has a dynamic Mediator API for accessing data through untyped calls (for example, getString("CUSTOMER_NAME")). An untyped Mediator API is useful if you do not know the data service to run at development time.

The Mediator API gives client applications full access to data services deployed on a WebLogic server. The application can invoke read functions, get the results as Service Data Objects, and pass changes back to the source. To use the Mediator API, a client program must first establish an initial context with the server that hosts the data services. The client can then invoke data service queries and operate on the results as Service Data Objects.

 

7.1 Running a Java Program Using the Untyped Mediator API

An untyped Mediator API is useful if, at development time, you do not know the data service to run.

Objectives

In this exercise, you will:

Instructions

  1. Add a Java project to your application by completing the following steps:
    1. Right-click the Evaluation application folder.
    2. Select Import Project.
    3. Select Java Project.
    4. Click Browse and navigate to:
      5.  <beahome>\weblogic81\samples\liquiddata\EvalGuide
    5. Select DataServiceClient, click Open, and then click Import.
      6. Figure 7-1 Importing Java Project


      Importing Java Project

      The Java project is added to the application, in the DataServiceClient folder. To use the Mediator API, you need to add the method calls to instantiate the data service, invoke the getCustomerProfile() method and assign the return value of the function to the CustomerProfileDocument SDO/XML bean.

  2. Open the DataServiceClient.java file, located in the DataServiceClient folder.
  3. Insert the method calls necessary to use the Mediator API, by completing the following steps:
    1. Add the following import statements at the beginning of the file:
      2. import com.bea.dsp.dsmediator.client.DataService;
      import com.bea.dsp.dsmediator.client.DataServiceFactory;
    2. Locate the main method. You will see a declaration of the data service, a String params[ ], plus the CustomerProfileDocument variable.
      3. Figure 7-2 Java Source Code


      Java Source Code

    3. Confirm that the String params[ ], which is an object array consisting of arguments to be passed to the function, is set as follows:
      4. 	String params[] = {customer_id};
    4. Construct a new data service instance, by modifying the DataService ds = null line. The Mediator API provides a class called DataServiceFactory, which can be used to construct the new data service instance. Using the newDataService method, you can pass in the initial JNDI context, the application name, and the data service name as parameters. For example:
      5. DataService ds = DataServiceFactory.newDataService(
      getInitialContext(),                			// Initial Context
      "Evaluation",                				// Application Name
      "ld:DataServices/CustomerManagement/CustomerProfile" // Data Service Name
      );
    5. Change the invocation of the data service by modifying the CustomerProfileDocument doc = null line, as shown in the following code: 
      6. CustomerProfileDocument[] doc = (CustomerProfileDocument[]) ds.invoke("getCustomerProfile",params);
    6. Specify the first element of the customer profile array by changing the following code:
      7. Customer customer = doc.getCustomerProfile().getCustomerArray(0);

to: 

Customer customer = doc[0].getCustomerProfile().getCustomerArray(0);
    1. Review the inserted code and verify that it is similar to that displayed in Figure 7-3.
      2. Figure 7-3 Untyped Mediator API Code Added


      Untyped Mediator API Code Added

  1. Review the code included in the //Show Customer Data and //Show Order Data sections. This code will be used to retrieve customer information, all orders of that customer (order ID, order date, and total amount) and the line items of each order (product ID, price and quantity). The code should be similar to that displayed in Figure 7-4.
    2. Figure 7-4 Customer and Order Code


    Customer and Order Code

  2. Click the Start icon (or press Ctrl + F5) to compile your program (if a Confirmation message regarding debugging properties appears, then click OK). It may take a few moments to compile the program.
Note: WebLogic Server must be running. Confirm that the program returns the specified results by viewing the results in the Output window (if the Output window is not open, choose View Arrow symbolWindows Arrow symbol Output).
Figure 7-5 Results: Output Window

Results: Output Window

  1. (Optional) View the results in a standalone Java environment of your choice.
Note: To use the Mediator API outside of WebLogic Workshop, you need to add the following files to your classpath:

 

7.2 Running a Java Program Using the Typed Mediator API

With the typed mediator interface, you instantiate a typed data service proxy in the client, instead of using the generic data service interface. The typed data service interface may be easier to program and it improves code readability.

In this exercise, you will access data services from a Java client, using the typed SDO Mediator API. You will be provided with a generated API for your data service, which lets you directly invoke the actual functions as methods (for example, ds.getCustomerProfile(customer_id)).

Objectives

In this exercise, you will:

Instructions

  1. Build your application as an EAR file by completing the following steps:
    1. Choose Tools Arrow symbol Application Properties and click Build.
    2. In the Project build order section, place DataServices as the first project.
    3. Clear the Project: DataServiceClient checkbox, because this is not required for the EAR file.
    4. Click OK.
      5. Figure 7-7 Project Build Order


      Project Build Order

  2. Build the SDO Mediator Client, by completing the following steps:
    1. Right-click the Evaluation application and select Build Application from the pop-up menu.
    2. Right-click the Evaluation application again and select Build SDO Mediator Client. A message displays notifying you that an EAR file will be created.
    3. Click Yes when asked whether you want to build an EAR file.
Note: This confirmation box appears only the first time you build the SDO Mediator Client. However, to ensure that the latest EAR file is used while building the SDO Mediator Client, you must build the EAR before you build the SDO Mediator Client.
    1. Confirm that you see the following text in the Build window (if not open, choose View Arrow symbol Windows Arrow symbol Build):
      2. Generating SDO client API jar...
      clean:
      de-ear:
      build:
      [delete] Deleting: C:\bea\user_projects\applications\Evaluation\Evaluation-ld-client.jar
      [mkdir] Created dir: C:\Documents and Settings\jsmith\Local Settings\Temp\wlw-temp-53911\sdo_compile42918\client\src
      [java] May 2, 2006 6:41:26 PM com.bea.ld.context.MetadataContext getRepositoryRoot
      [java] INFO: 30 (ms)
      [java] May 2, 2006 6:41:27 PM com.bea.ld.wrappers.ws.JAXRPCWebserviceAdapter <clinit>
      [java] WARNING: Unable to instantiate ServiceFactory. Please ensure that javax.xml.rpc.ServiceFactory property has been properly set.
      [mkdir] Created dir: C:\Documents and Settings\jsmith\Local Settings\Temp\wlw-temp-53911\sdo_compile42918\client\classes
      [javac] Compiling 12 source files to C:\Documents and Settings\jsmith\Local Settings\Temp\wlw-temp-53911\sdo_compile42918\client\classes
      [jar] Updating jar: C:\bea\user_projects\applications\Evaluation\Evaluation-ld-client.jar
      all:
      Importing SDO client API jar into application...
      SDO client API jar available as C:\bea\user_projects\applications\Evaluation\Evaluation-ld-client.jar
Note: The drive information may be different for your application.
  1. Construct a new data service instance and invoke the data service, by completing the following steps:
    1. Open the DataServiceClient.java file (if it is not already open).
    2. Replace the declaration of the DataService and CustomerProfileDocument objects with the following (modified code is displayed in boldface type):
      3. CustomerProfile ds = CustomerProfile.getInstance(
      getInitialContext(), 		// Initial Context
      "Evaluation" 			// Application Name
      );
      CustomerProfileDocument doc = ds.getCustomerProfile(customer_id);
      Note: In the case of typed mediator APIs, you specify whether you are retrieving a single object or an array based on the data service function declaration. In the preceding example, to retrieve a single object in the output, the doc object is used instead of doc[0].
    3. Click Alt + Enter and select dataservices.customermanagement.CustomerProfile. This creates an import statement at the beginning of the file for the specified data service.
    4. Edit getInitialContext () to suit your environment. Typically no changes are needed when working through the tutorial on your local computer.
  2. View the results in the Output window, by completing the following steps:
    1. Click the Start icon (or press Ctrl + F5) to compile your program.
    2. Click OK if a confirmation message asking if you would like to run DataServiceClient.
    3. Confirm that the program return the specified results by viewing the results in the Output window (if not open, choose View Arrow symbol Windows Arrow symbol Output).
      4. Figure 7-8 Results -- Output Window


      Results -- Output Window

  3. (Optional) Run your program in a standalone Java application to list customer orders. Note that you must add the generated file (the typed data-service proxy, Evaluation-ld-client.jar) to the classpath, along with the other libraries listed for Excercise 7.1 Running a Java Program Using the Untyped Mediator API, (optional) step 7.
    4. Figure 7-9 Results-- Standalone Java Application


    Results-- Standalone Java Application

 

7.3 Resetting the Mediator API

After Excercise 7.2 Running a Java Program Using the Typed Mediator API, you must remove the Evaluation_ld-client.jar file from your Libraries folder because this JAR file will create inconsistencies in future lessons. You must also revert the method calls to use the Untyped Mediator API.

Objectives

In this exercise, you will:

Instructions

  1. Delete the Evaluation-ld-client.jar file by completing the following steps:
    1. Expand the Libraries folder.
    2. Right-click the Evaluation-ld-client.jar file.
    3. Choose Delete from the pop-up menu.
    4. Click Yes, when the confirmation message displays.
  2. Revert the method calls to use the untyped mediator API, by completing the following steps:
    1. Open the DataServiceClient.java file.
    2. Replace the declaration of the DataService and CustomerProfileDocument objects with the following (modified code is displayed in bold):
      3. DataService ds = DataServiceFactory.newDataService(
      getInitialContext(),                			// Initial Context
      "Evaluation",                				// Application Name
      "ld:DataServices/CustomerManagement/CustomerProfile" 	// Data Service Name
      );
      CustomerProfileDocument[] doc = (CustomerProfileDocument[]) 
      ds.invoke("getCustomerProfile", params);
      System.out.println("Connected to DSP 2.x : CustomerProfile Data Service...");
      Note: If your application name is different from Evaluation, locate "Evaluation" in the newDataService() call and rename it to reflect the name of your application.
    3. Remove the import CustomerProfile statement.
    4. Save your work.

 

Lesson Summary

In this lesson, you learned how to:


  Back to Top       Previous  Next