|
|
This chapter describes how you can use Data Service controls in applications generated by Workshop for WebLogic. The following topics are included:
An Data Service control enables Workshop for WebLogic Platform applications to easily access data services. When you use an Data Service control to invoke data service functions, you get information back as a data object. A data object is a unit of information as defined by the Service Data Objects (SDO) specification. For more information on SDO, see Chapter 2, “Data Programming Model and Update Framework.”
In addition to the functionality discussed in this chapter, Data Service controls provide many of the same features available through the SDO Mediator API, including:
For more information on these features, see Chapter 8, “Advanced Topics.”
An Data Service control provides access to Oracle Data Service Integrator dataspaces within Workshop for WebLogic Platform. It is a wizard-generated Java file that can be used to access data service operations. These operations can be added to an Data Service control from data services deployed on any accessible Oracle WebLogic Server, both local or remote. The Data Service control wizard retrieves all available data service operations on the server. It then lets you choose the ones to include in your control.
| Note: | All client APIs, including Data Service control, support calling data service functions without parameters. Data service functions with optional parameters can be called within other data service functions or from an ad hoc query, but such functions cannot be invoked using a Data Service control itself. |
Like Java controls, you can use an Data Service control in Workshop for WebLogic Platform applications such as Web services, page flows, and WebLogic integration business processes. After applying the control to a client application, you can use the data returned from query functions in the control in your application.
This chapter describes how to use an Data Service control in a web service project application. The steps for using it in other Workshop for WebLogic Platform projects are similar.
When you create an Data Service control, Workshop for WebLogic Platform generates a Java Control file (.java) that contains methods based on the data services functions, and a commented method that can be uncommented and used to pass any XQuery statements (called ad hoc queries) to the server.
The Design View tab of the Java web services displays a graphical view of the data service methods that were selected for inclusion in the control.
The Source View tab shows the source code of the Data Service control. It includes annotations defining the data service function names associated with each method. For update functions, the data service bound to the update is the data service specified by the locator attribute. For example:
locator = "1{ld:ADDRESS}updateADDRESS", functionKind = "procedure")The signature for the method shows its return type. The return type for a read method is an SDO object corresponding to the schema type of the data service that contains the referenced function. The SDO classes corresponding to the data services used in an Data Service control reside in the Libraries folder of the project. An interface is generated for each data service.
The only time you should need to manually edit the source code is if you want to add a method to run an ad hoc query, as described in Using Data Service control for Ad Hoc Queries.
Listing 6-1 shows portions of a generated Data Service control file. It shows the package declaration, import statements, and data service URI used with the queries.
package xyzpackage;
import org.apache.beehive.controls.api.bean.ControlExtension;
import com.bea.dsp.control.core.DSPControl;
import com.bea.dsp.control.core.annotation.DSPControlInterfaceAnnotation;
import com.bea.dsp.control.core.annotation.ALDSPControlMethodAnnotation;
import com.bea.dsp.RequestConfig;
import commonj.sdo.DataObject;
import com.bea.sdo.impl.data.DataObjectGeneral;
@ControlExtension
@DSPControlInterfaceAnnotation(version = "3.0" , application = "DS2", urlKey = "DS2.xyzpackage.xyz_DSPControlFile", url = "t3://localhost:7001", username = "weblogic")
public interface xyz_DSPControlFile extends DSPControl {
@ALDSPControlMethodAnnotation(functionURI = "ld:ADDRESS", functionName ="ADDRESS", schemaURI = "ld:ADDRESS", schemaRootElement = "ADDRESS", locator = "0{ld:ADDRESS}ADDRESS", functionKind = "function")
public address.ADDRESS[] ADDRESS() ;
@ALDSPControlMethodAnnotation(functionURI = "ld:ADDRESS", functionName ="createADDRESS", schemaURI = "ld:ADDRESS", schemaRootElement = "ADDRESS_KEY", locator = "1{ld:ADDRESS}createADDRESS", functionKind = "procedure")
public address.ADDRESS_KEY[] createADDRESS(address.ADDRESS[] p) ;
@ALDSPControlMethodAnnotation(functionURI = "ld:ADDRESS", functionName ="updateADDRESS", schemaURI = "", schemaRootElement = "", locator = "1{ld:ADDRESS}updateADDRESS", functionKind = "procedure")
public void updateADDRESS(address.ADDRESS[] p) ;
@ALDSPControlMethodAnnotation(functionURI = "ld:ADDRESS", functionName ="deleteADDRESS", schemaURI = "", schemaRootElement = "", locator = "1{ld:ADDRESS}deleteADDRESS", functionKind = "procedure")
public void deleteADDRESS(address.ADDRESS[] p) ;
@ALDSPControlMethodAnnotation(functionURI = "ld:ADDRESS", functionName ="getCREDIT_CARD", schemaURI = "ld:CREDIT_CARD", schemaRootElement = "CREDIT_CARD", locator = "1{ld:ADDRESS}getCREDIT_CARD", functionKind = "function")
public credit_card.CREDIT_CARD[] getCREDIT_CARD(address.ADDRESS pk) ;
@ALDSPControlMethodAnnotation(functionURI = "ld:ADDRESS", functionName ="getCUSTOMER", schemaURI = "ld:CUSTOMER", schemaRootElement = "CUSTOMER", locator = "1{ld:ADDRESS}getCUSTOMER", functionKind = "function")
public customer.CUSTOMER[] getCUSTOMER(address.ADDRESS fk) ;
/**
* Using RequestConfig:
* In order to use a RequestConfig parameter with functions,
* procedures and submit methods
* please edit a method signature as follows:
* From:
* Customer getCustomer(java.lang.String p0);
* To:
* Customer getCustomer(java.lang.String p0, RequestConfig
* config);
* The RequestConfig parameter allows you to send FilterXQuery and
* QueryAttributes
* to the server and receive Audit Event. **/
| Note: | The read operations do not contain the control level flag for txRequired and txSupported. This flag is available in RequestConfig and is applied on a per-call basis. |
You can create a Data Service control in Workshop for WebLogic. The general steps to create an Data Service control are:
The following sections describe each of these steps in detail.
Before you can create an Data Service control in Workshop for WebLogic, you must create a web-enabled project such as portal or Web Service Project. A Web Service Project allows you to create Java web service projects while you can use a dynamic web project to create portal components like Java page flows and JSPs.
Make sure that the Oracle WebLogic Server that hosts the Oracle Data Service Integrator dataspace project is running. Oracle WebLogic Server can be running locally (on the same domain as Workshop for WebLogic) or remotely (on a different domain from Workshop for WebLogic).
In the web-enabled project or Web Service Project, an src folder is created. Create a package under this folder as follows:
To create an Data Service control:
| Note: | A Data Service control can be created only in a project that is enabled with Beehive facets because the Beehive runtime is required for the Data Service control runtime. If you select a container that is not Beehive-enabled, you will not be able to proceed. |
To check for the Beehive Control facets:
| Note: | A control can only invoke data service functions from a single dataspace project. |
| Note: | You can choose to generate an ODSI Control from dataspace projects in your local workspace instead of a deployed dataspace. However this option is available only if your Workshop platform can support Oracle Data Service Integrator, otherwise it is disabled. This option will be enabled in a future release of Oracle Data Service Integrator. |
Select the From server option and then:
| Note: | An Data Service control can access only public data service functions. |
After creating the control, the following files are created:
DSP_Control.jar: This JAR contains the required runtime components and is available under the WebApp Libraries folder. aldspschemas_controlctrl_xsd_full_package_name.jar
| Note: | Oracle Data Service Integrator generates interface files for the target schemas associated with the queries and the ODSI Control file. |
The location of both these JAR files is shown in Figure 6-6.
Client applications can issue ad hoc queries against data service functions. You can use ad hoc queries when you need to change the way a data service function returns data. Ad hoc queries are most often used to process data returned by data services deployed on a Oracle WebLogic Server. Ad hoc queries are especially useful when it is not convenient or feasible to add functions to an existing data service.
An Data Service control generated from a wizard contains a commented ad hoc query method template that can serve as a starting point for creating an ad hoc query. To create the ad hoc query:
com.bea.xml.Object executeQuery(String query);
Replace the function name with a meaningful name for your application. Be default, the ad hoc query returns a typed SDO or an object that matches the return type for the ad hoc query. You can also optionally supply ExternalVariables or QueryAttributes (or both) to an ad hoc query.
| Note: | ExternalVariable is used for binding variable name to value for use in adhoc query in Data Service control. In Data Service control, an xquery can be passed in as a string. If this query has declared external variables, then the value for these variables are passed in using ExternalVariable. |
When invoking this ad hoc query function from an Data Service control, the caller needs to pass the query string (and the optional ExternalVariables binding and QueryAttributes). For example, an ad hoc query signature in a Data Service control will look like the following:
@DSPControlAdhocQueryAnnotation(body="")
* Object[] executeQuery(String xquery, ExternalVariables params);
}
The code to call this Data Service control (from a web service JWS file, for example) would be:
public void adHocAddressQuery()
{String adhocQuery =
"declare namespace f1 = \"ld:ldc_produucerDataServices/ADDRESS\";\n" +
"declare namespace ns0=\"ld:ldc_produucerDataServices/ADDRESS\";\n"+
"<ns0:ArrayOfADDRESS>\n"+"{for $i in f1:ADDRESS()\n" +"where $i/STATE = \"TX\"\n"+" return $i}\n" +
"</ns0:ArrayOfADDRESS>\n";
Object result = myldcontrol.adHocAddressQuery(adhocQuery);
}
This section describes how you can modify an existing Data Service control. When you edit a control, the SDO classes that are available to the control are recompiled, which means that any changes to data service are incorporated to the controls also.
This section contains the following topics:
To change a data service function in an Data Service control:
If any of the schemas corresponding to any operation in an Data Service control change, you need to edit the control by removing the operation and restoring it.
When you edit the control, its SDO classes are automatically regenerated.
| Note: | For details on working with static and dynamic SDO see “Mediator API Basics” on page 3-41. |
The following scenario is very common: most of the time you can use cached data because it changes infrequently; however, on occasion, your application must fetch data directly from the data source. At the same time, you want to update your cache with the most up-to-date information. A typical example would be to refresh the cache at the beginning of every week or month.
You can accomplish this by passing the attribute GET_CURRENT_DATA with your function call.
To bypass the data in a cached query function result, your application will need to signal Oracle Data Service Integrator to retrieve results directly from the data source, rather than from its cache. The steps required to accomplish this include:
Listing 6-2 shows example Java Page Flow (JPF) code that tests whether the user has requested a bypass of any cached data. If refreshCache is set to False then cached data (if any is available) is used. Otherwise the function will be invoked with the GET_CURRENT_DATA attribute and data will be retrieved from the data source. As a by-product, any cache is automatically refreshed.
if (refreshCache == false) { address.ADDRESS[] addresses = control.ADDRESS();
} else { QueryAttributes attr = new QueryAttributes();
attr.enableFeature (QueryAttributes.GET_CURRENT_DATA);
address.ADDRESS[] addresses = control.ADDRESS(attr);
}
An additional function is also needed in the Data Service control file. For the code shown in Listing 6-2, you need to add the following definition to the control:
@ALDSPControlMethodAnnotation(functionURI = "ld:ADDRESS", functionName ="ADDRESS", schemaURI = "ld:ADDRESS", schemaRootElement = "ADDRESS", locator = "0{ld:ADDRESS}ADDRESS", functionKind = "function") public address.ADDRESS[] ADDRESS(QueryAttributes attr) ;
This section describes security considerations for applications using an Data Service control. The following sections are included:
When you create an Data Service control and connect to a local or remote Oracle Data Service Integrator server (a Oracle WebLogic Server on a different domain from Workshop for WebLogic Platform), you specify the connection information in the Data Service control wizard as shown in Figure 6-3.
When you create an Data Service control, the Data Service control Wizard displays all queries to which the specified user has access privileges. The access privileges are defined by security policies set on the queries, either directly or indirectly.
To test an Data Service control:
When a query is run from a dataspace, it must have a mechanism for getting the security credential. The credential can come from a login screen, it can be hard-coded in the dataspace, or it can be imbedded in a J2EE component (for example, using the run-as property in a JWS Web service file).
| Note: | You can enable the auditing if you want to monitor or debug Data Service control in a test environment. For more information about auditing, refer to the Working With Audit and Log Information chapter in the Administration Guide. |
If the Oracle WebLogic Server that hosts the Oracle Data Service Integrator project is on a different domain than Workshop for WebLogic Platform, then both domains must be set up as trusted domains.
Domains are considered trusted domains if they share the same security credentials. With trusted domains, a user known to one domain need not be authenticated on another domain, if the user is already known on that domain.
| Note: | After configuring domains as trusted, you must restart the domains before the trusted configuration takes effect. |
For more details on WebLogic Server security, see:
For information on security, see:
If you deploy your application on a server, which is the source for Data Service control between different domains, then you must create a dspControlConfig.properties file in the domain directory of the cluster where Data Service control is deployed.
This property file should contain a key-value mapping where the key is the string representing the urlKey in the control file and the value is the T3 URL at which Oracle Data Service Integrator server is found.
For example, if your Data Service control file contains urlKey = "ValidSample.com.LocalCtrl", then your property file should contain ValidSample.com.LocalCtrl=t3://<my-qa-prod-dev-url>.
Ensure that for each Data Service control that you deploy, there is a corresponding dspControlConfig.properties file entry.
|
