Working with Descriptor Properties

Class Tab

To add a new interface to implement, click Add.

To delete an interface, select the interface and click Remove.

To generate source code for the descriptor, click Generate Source Code.

Figure 4-2 Class Tab

Description of the illustration clinclas.gif

Use this table to enter data in each field:

Attributes Tab

To add a new attribute, click Add.

To delete an existing attribute, select the attribute and click Remove.

To rename an existing attribute, select the attribute and click on Rename.

Figure 4-3 Attributes – General Tab

Description of the illustration clinatt.gif

Select an attribute, then use this table to enter data in each field on the General tab.

Figure 4-4 Attributes – Accessors Tab

Description of the illustration clinatta.gif

Select an attribute, then use this table to enter data in each field on the Accessors tab.

To generate a get or set method for an attribute, click Generate Get/Set Methods.

Methods Tab

To add a new method, click Add.

To delete an existing method, select the method and click Remove.

Figure 4-5 Methods Tab

Description of the illustration clinmeth.gif

Select a method, then use this table to enter data in each field:

Custom SQL Queries

Use this procedure to create custom SQL queries in the OracleAS TopLink Mapping Workbench. For 2.0 CMP projects, the SQL is not written to the ejb-jar.xml file.

To create custom SQL queries:

1. In the Navigator pane, select a descriptor.

2. Click the Queries tab in the Editor pane.

3. Click the Custom SQL tab.

   Figure 4-6 Queries Custom SQL Tab

   
   Description of the illustration qrsqltab.gif
   
   

4. Click the appropriate SQL function tab and type your own query object or SQL string to control these actions for a descriptor.

Custom QueriesTo control the five custom query tabs, you can include your own query object or SQL string for a particular descriptor. The SQL string for each database is defined by the type of database. For example, the stored procedure to read an object may use the following string:Read_Employee(EMP_ID=>4653) The query manager requires the following string to read the object: Read_Employee(EMP_ID=>#EMP_ID)In this query, the hash character, #, binds the argument EMP_ID within the SQL string.

Named Queries

Use named queries to specify SQL, EJB QL, or OracleAS TopLink Expression queries to access the database. EJB QL is a declarative language that presents queries from an object-model perspective. Refer to the EJB specification and the Oracle Application Server TopLink Application Developer's Guide for detailed information.

To create a named query:

1. In the Navigator pane, select a descriptor.

2. Click the Queries tab in the Editor pane.

3. Click the Named Queries tab in the Queries tab. The Named Queries tab contains the following additional tabs:

   • Named Queries General tab

   • Named Queries Format tab

   • Named Queries Options tab

   Figure 4-7 Named Queries Tab

   
   Description of the illustration qrnmdfnd.gif
   
   

4. Click Add to create a new named query. The Add Named Query dialog box appears.

   Figure 4-8 Add named Query

   
   Description of the illustration addnmdqr.gif
   
   

5. Select the query type (for EJB descriptors), enter the query name, and press Enter. The OracleAS TopLink Mapping Workbench adds the query to the Named Query tab.

   
   

   Note: For OracleAS TopLink Reserved Finders, use the drop-down box to select a reserved name. OracleAS TopLink will generate the query at runtime.

   
   

6. Click on the General tab to specify the query type and parameters.

   Figure 4-9 Named Queries General Tab

   
   Description of the illustration qrnmdgen.gif
   
   

7. Use this table to enter data in each field on the General tab.

   Field	Description
   Descriptor Alias	Alias for the descriptor class. This field applies for EJB finders only.
   Name	Name of the query. The prefix of the query name specifies the query type: find – EJB 2.0 ejbSelect – EJB Select You cannot change the name of OracleAS TopLink Reserved Finders.
   Type	Use the drop-down list to specify whether this is a ReadObject or ReadAll query.
   Parameters	Click Add to add a parameter of a specific type to this query. Note: You cannot add parameters for EJB descriptors.

   
   

8. Click on the Format tab to specify the named query and its format.

   Figure 4-10 Named Queries Format Tab

   
   Description of the illustration qrnmdfor.gif
   
   

9. Use this table to enter data in each field on the Format tab.

   Field	Description
   Expression	Specify this named query uses an OracleAS TopLink expression.
   SQL	Specify this named query is a SQL query.
   EJB QL	Specify this named query is an EJB QL query.
   Query String	Entry the query. The OracleAS TopLink Mapping Workbench does not validate the query string. Note: For Expressions, double-click the query string or click Edit to create or edit the query string. See "Building Expressions" for more information.

   
   

10. Click on the Options tab to specify additional options for the named query.

    
    

    Note: If the options on this panel are disabled, the Mapping Workbench uses the options specified in the parent.

    
    

    Figure 4-11 Named Queries Options Tab

    
    Description of the illustration qrnmdopt.gif
    
    

11. Use this table to enter data in each field on the Options:

    Field	Description
    Refresh Identity Map Results	Specify the refreshIdentityMapResults() method to refresh the attributes of the object resulting from the query.
    Cache Statement	Specify the cacheStatement() method for the query. If undefined, the query uses the project's default settings (see "Working with Default Properties" on page 2-9). If true, then Bind Parameters must be true as well.
    Bind Parameters	Specify the bindAllParameters() method for the query. If undefined, the query uses the project's default settings (see "Working with Default Properties" on page 2-9).
    Cache Usage	Select if/how the query checks the cache before accessing the database.
    In Memory Query Indirection	Specify how a query reacts when accessing un-instantiated indirection. Use this option to specify the InMemoryQueryIndirectionPolicy policy.

    
    
    
    

    Note: These options are not available for findOneByQuery and findManyByQuery.

    
    

12. Click Advanced to specify additional named query options.

    Figure 4-12 Advanced Query Options

    
    Description of the illustration advqropt.gif
    
    

13. Use this table to enter data in each field and click OK:

Refer to the Oracle Application Server TopLink Application Developer's Guide for additional information on named queries.

Adding Arguments

Each expression contains elements (arguments) to evaluate. Expressions using the Is Null or Not Null operators require only a single argument.

Use this procedure to add new arguments.

1. Select an existing expression or click Add (or Add Nested) to add a new expression to the named query.

2. For the First Argument, click Edit. The Choose Query Key dialog box appears.

   Figure 4-14 Choose Query Key

   
   Description of the illustration choseqk.gif
   
   

3. Select the attribute, specify if the query allows a null value, and click OK.

4. Use the Operator drop-down list to specify how OracleAS TopLink should evaluate the expression.

5. For the Second Argument, select Literal, Query Key, or Parameter, and click Edit.

   • For Literal arguments, the Edit the Literal Type and Value dialog box appears. Choose the literal type (such as String or Integer) and value.

   • For Query Key arguments, the Choose Query Key dialog box appears (see Figure 4–14).

   • For Parameter arguments, use the drop-down list to select the specific parameter, as created on the Named Queries General tab (see Figure 4–9).

Repeat this procedure for each expression or sub-expression.

AND
  1.manager(Allows Null).lastName EQUAL "Jones"
  2.OR
    2.1.projects.name LIKE "BETA"
    2.2.projects.id EQUAL "4"
  3.OR
    3.1.AND
      3.1.1.address.country EQUAL "Canada"
      3.1.2.salary GREATER THAN "25000"
    3.2.AND
      3.1.1.address.country EQUAL "United States"
      3.1.2.salary GREATER THAN "37500"

• Have a manager with the last name Jones or have no manager, and

• Work on projects with the name Beta or project ID 4, and

• Live in Canada and have a salary of more than 25,000 or Live in the United States and have a salary of more than 37,500

Specifying Query Keys

Use the Query keys tab to specify a query key for a descriptor.

To specify query keys:

1. Select a descriptor in the Navigator pane. Its properties appear in the Editor pane.

2. Click the Query Keys tab in the Editor pane.

   Figure 4-15 Query Keys Tab

   
   Description of the illustration querykey.gif
   
   

3. To add a new query key, click Add.

   To delete an existing query key, select the query key and click Remove.

   To rename an existing query key, select the query key and click Rename.

4. Use the Field drop-down list to select the field in the table used by the query.