9.4 Query Namespaces

Two namespaces exist in JDOQL queries; they contain:

• The names of types

• The names of fields, parameters, and variables

Parameters and variables are given a name and type when they are declared. The types of the parameters and variables are placed in the first namespace; the parameter and variable names are placed in the latter namespace.

9.4.1 Type Names

When a type name is used (e.g., in a parameter or variable declaration), it must be one of the following:

• The name of the candidate class

• The name of a class or interface declared in the java.lang package

• The name of a class or interface imported by a call to declareImports( )

• The name of a class or interface in the same package as the candidate class

• A name imported by a type-import-on-demand declaration, as in "import <package>.*;"

The type namespace automatically includes the name of the candidate class and the names of other classes in the same package. It also automatically includes the names of the public types declared in the java.lang package, just as if there had been a type-import-on-demand declaration (import java.lang.*).

You must include any additional types names necessary for the types of parameters and variables. You import the types into a Query instance by calling the following Query method:

void declareImports(String imports);

The String parameter imports contains one or more import statements, separated by a semicolon. The syntax of the parameter is identical to Java's import statements. All imports must be declared in the same call to declareImports( ).

For example, we may have a query that accesses the Transaction instances associated with a Customer, returning those with an acquisitionDate field that is greater than a specific Date value. This query would have a Transaction variable used to reference the elements of the transactionHistory collection in Customer. It would also have a query parameter of type Date. We would specify the following import declaration:

query.declareImports(
             "import com.mediamania.store.Transaction; import java.util.Date");

The declareImports( ) method adds the names of the imported class or interface types into the type namespace. It is valid to specify the same import multiple times. When a query is compiled, an error occurs if you have more than one type-import-on-demand declaration and the same type name (excluding the package name) is imported from more than one package. In this case, the specific type to which a type name refers would be ambiguous. This error is reported when you call compile( ) or execute( ).

9.4.2 Field, Parameter, and Variable Names

The other query namespace contains the names of fields, parameters, and variables. The names of the fields in the candidate class are automatically placed in this namespace. The declareParameters( ) method introduces the parameter names, and the declareVariables( ) method introduces the variable names. The parameter and variable names must be unique, so their use is not ambiguous in the query filter.

The this keyword can be used in the query filter to denote the current candidate instance being evaluated. This reference can be used as an operand of the expressions in the query filter. It is possible to have a parameter or variable name with the same name as a field in the candidate class. In this case, the candidate class field is hidden. You can use this to access any fields of the candidate class that may be hidden by a parameter or variable of the same name. The hidden field is accessed by using the this qualifier: this.fieldName. However, we recommend that you use parameter and variable names that are unique and distinct from the field names. Your queries will be shorter and easier for others to understand.

9.4.3 Keywords

JDOQL defines keywords in the following categories:

• Primitive type names: boolean, byte, short, int, long, char, float, double

• Boolean literals: true, false

• Expressions: null, this

• Import declarations: import

• Ordering specification: ascending, descending

You cannot use these keywords as field names, though most of them are Java keywords anyway. The exceptions are ascending and descending; you will not be able to use fields with these names in a query.

9.4.4 Literals

Expressions in a query filter can include literals of the following types:

• int, long (42, -7, 2048L, 4096l)

• float, double (3.14, 3.14f, 3.14F, 0.6180339887d, 1.6180339887D)

• boolean (true, false)

• char ('J')

• String ("JDO is great!")

• null

The syntax used for these literals is identical to their syntax in Java, as described in the Java Language Specification.