Named Queries

When you use a session query method like readAllObjects (see "Session Queries"), TopLink creates a corresponding ReadAllQuery, which builds other objects it needs to perform its task. When TopLink finishes execution of the readAllObjects method, these objects are discarded. Each time you call this session method, TopLink creates these related objects again, uses them once, and then discards them.

Alternatively, you can create a DatabaseQuery (see "Database Queries") and store it by name at the descriptor- (see "Configuring Named Queries at the Descriptor Level") or session-level (see "Configuring Named Queries at the Session Level").

TopLink prepares a named query once, and it (and all its associated supporting objects) can be efficiently reused thereafter making a named query well suited for frequently executed operations.

Using the Session API (see "Using Named Queries"), you can execute these queries by name, passing in any required arguments.

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

When to Use Named Queries

For a reasonably complex query that you execute frequently, you should consider making the query a named query.

If a query is global to a project, configure the named query at the session level ("Configuring Named Queries at the Session Level").

If a query is global to a Class or you want to configure CMP finders, configure the named query at the descriptor level (see "Configuring Named Queries at the Descriptor Level"). For more information about descriptor level query configuration, see "Descriptor Query Manager Queries".

For a very complex query, you can delegate query execution to your own static method using a special form of a named query called a redirect query. For more information about redirect queries, see "Redirect Queries").

When Not to Use Named Queries

Rarely used queries may be more efficient when built on an as-needed basis. If you seldom use a given query, it may not be worthwhile to build and store that query when you invoke a session.