Skip Headers

Oracle TopLink Developer's Guide 10g Release 3 (10.1.3) B13593-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# Call Queries

All session types provide `executeSelectingCall` and `executeNonSelectingCall` methods that take any of the following `Call` types:

- SQL Calls

- EJB QL Calls

- Enterprise Information System (EIS) Interactions

You can also execute a `Call` in the context of a `DatabaseQuery`. For more information on `DatabaseQuery`, see "Database Queries".

WARNING: Allowing an unverified SQL string to be passed into methods (for example: `executeSelectingCall(String sql)` method) makes your application vulnerable to SQL injection attacks.

## SQL Calls

SQL calls access fields in a relational database. TopLink supports the following SQL calls:

- SQLCall

- StoredProcedureCall

- StoredFunctionCall

Using the `Call` API (or SQL string conventions), you can specify input, output, and input-output parameters and assign values for input and input/output parameters.

Using a descriptor `ReturningPolicy`, you can control whether or not TopLink writes a parameter out, retrieves a value generated by the database, or both. For more information, see "Configuring Returning Policy".

### SQLCall

Using a `SQLCall`, you can specify any arbitrary SQL statement and execute it on a data source.

WARNING: Allowing an unverified SQL string to be passed into methods makes your application vulnerable to SQL injection attacks.

For more information, see "Using an SQLCall".

### StoredProcedureCall

A stored procedure is composed of one or more procedural language statements, such as Procedural Language/Structured Query Language (PLSQL), stored by name in the database. Most relational databases support stored procedures.

You invoke a stored procedure to execute logic and access data from the data source.

Using a `StoredProcedureCall`, you can detect execution errors, specify input parameters, output parameters, and input/output parameters. However, stored procedures do not provide a return value.

For more information, see "Using a StoredProcedureCall".

### StoredFunctionCall

A stored function is an Oracle9i (or later) feature that provides all the functionality of a stored procedure as well as the ability to return a value.

Using a `StoredFunctionCall`, you can specify all the features of a `StoredProcedureCall` as well as the field name of the return value.

For more information, see "Using a StoredFunctionCall".

### Oracle Extensions

When you use TopLink with an Oracle9i (or later), you can make use of the following Oracle specific query features from within your TopLink applications:

- Hints

- Hierarchical Queries

- Flashback Queries

- Stored Functions

#### Hints

Oracle9i (or later) lets you specify SQL query additions called hints that can influence how the database server SQL optimizer works. This lets you influence decisions usually reserved for the optimizer. You use hints to specify things such as join order for a join statement, or the optimization approach for a SQL call.

You specify hints using the `DatabaseQuery` method `setHintString`.

For more information, see the following:

- "Database Queries"

- "Oracle Hints"

- Your database Performance Tuning Guide and Reference.

#### Hierarchical Queries

Oracle database Hierarchical Queries mechanism lets you select database rows based on hierarchical order. For example, you can design a query that reads the row of a given employee, followed by the rows of people the employee manages, followed by their managed employees, and so on.

You specify a hierarchical query clause using `DatabaseQuery` subclass `ReadAllQuery` method `setHierarchicalQueryClause`. For more information on `DatabaseQuery` queries, see "Database Queries".

For more information on configuring a `ReadAllQuery` with an Oracle hierarchical query clause, see "Hierarchical Queries".

#### Flashback Queries

When using TopLink with Oracle9i (or later), you can acquire a special historical session where all objects are read as of a past time, and then you can express read queries depending on how your objects are changing over time.

For more information, see "Historical Queries".

#### Stored Functions

A stored function is an Oracle database mechanism that provides all the capabilities of a stored procedure in addition to returning a value.

For more information, see "StoredFunctionCall".

## EJB QL Calls

In TopLink, EJB QL calls represent EJB QL strings. An `EJBQLCall` object is an abstraction of a database invocation. You can execute an EJB QL call directly from a session or in the context of a `DatabaseQuery`.

To populate a query using the information retrieved from parsing the EJB QL string, use the EJBQLCall method `populateQuery`.

For more information, see the following:

- "Using EJB QL Calls"

- "Specifying a Custom EJB QL String in a DatabaseQuery"

- "EJB QL Queries"

## Enterprise Information System (EIS) Interactions

To invoke a query through a J2EE Connector Architecture (J2C) adapter to a remote EIS, you use an `EISInteraction`, an instance of `Call`. TopLink supports the following `EISInteraction` types:

- IndexedInteraction

- MappedInteraction

- XMLInteraction

- XQueryInteraction

- QueryStringInteraction

In each of these interactions, you specify a functional interface (similar to a stored procedure) that identifies the function to invoke on the EIS. This functional interface contains the following:

- The function name

- The record name (if different than the function name)

- A list of input arguments

- A list of output arguments

For more information, see

- "EIS Projects"

- "Using EIS Interactions"

### IndexedInteraction

In an `IndexedInteraction`, you exchange data with the EIS using indexed records. The order of the specification of the arguments must match the order of the values defined in the indexed record.

### MappedInteraction

In a `MappedInteraction`, you exchange data with the EIS using mapped records. The arguments you specify map by name to fields in the mapped record.

### XMLInteraction

An `XMLInteraction` is a `MappedInteraction` that maps data to an XML record. For an `XMLInteraction`, you may also provide an optional root element name.

### XQueryInteraction

If your J2C adapter supports the XQuery dynamic query language, you can use an `XQueryInteraction`, which is an `XMLInteraction` that lets you specify your XQuery string.

### QueryStringInteraction

If your J2C adapter supports a query string based dynamic query language, you can use a `QueryStringInteraction`, which is a `MappedInteraction` that lets you specify the dynamic query string.