![]() |
Special Cloudscape Programming
|
Reference Manual |
Programming Orderable ClassesCloudscape allows you to perform ordering, comparisons operations, and index creation on special Java data types called orderable Java data types. (For a complete list of their capabilities and SQL-J examples, see Orderable Java Data Types in the Cloudscape Reference Manual. For more SQL-J examples, see Orderable Java Data Types.) This section discusses how details of creating orderable Java data types and provides detailed implementation notes. It also discusses requirements for Java data types that will use the = or <> comparison operators (not just orderable Java data types).
Requirements for Orderable Java Data TypesCloudscape can put objects in the correct order if those objects provide a special method for that purpose, the compareTo method. Therefore, to qualify as an orderable Java data type, a Java class must meet the following requirements:
Given these rules, a Java data type should be orderable in both environments, thus allowing a database to move freely between a JDK 1.1 and a JDK1.2 environment. Notes on compareTo ImplementationThe behavior of the compareTo method is defined by the JDK 1.2 interface java.lang.Comparable, which is copied here:
NOTE: On this last point, although the JDK rules only strongly recommend that the ordering be consistent with equals, Cloudscape requires it. Any ordering or index maintenance in Cloudscape depends on the correct implementation of the compareTo method. If a class's compareTo method does not follow the implementation rules, the results of any query involving such an object are not defined. It is also expected that calling the compareTo method of an object does not change the state of the object or that of the passed in object. NOTE: The compareTo method should not do anything bizarre such as make random comparisons, call database-side JDBC, or alter the object. In addition, the method should be time-invariant. That is, a.compareTo(b) must return the same thing forever. So, it should not depend on things like the current date. Otherwise, an index built today could be inconsistent tomorrow. NOTE: compareTo and equals must work correctly with subclasses. If you define a column to serialize a particular class or interface, all subclasses that you store in the column must implement the Orderable interface in exactly the same way as the superclass. They must use the same ordering as the superclass. Notes on Implementing the equals and hashCode MethodsThe operators = and <> are allowed even on non-orderable Java data types provided that they correctly implement the following methods: (See Java Data Types and Equality Operations in the Cloudscape Reference Manual.) The behavior of the equals method is defined by the class java.lang.Object. The API documentation is copied here:
The behavior of the hashCode method is also defined by the API. Typically implementation of hashCode is related to implementation of equals. If a Java data type is orderable, Cloudscape uses the type's compareTo method (not the equals method) to implement the = and <> operators. Cloudscape may use the hashCode method for DISTINCT operations. Therefore, correct comparisons in Cloudscape depend on the correct implementation of the compareTo or equals methods. If a class's compareTo or equals method does not follow the implementation rules the results of any query involving such an object are not defined. NOTE: The equals method should not do anything bizarre such as make random comparisons, call database-side JDBC, or alter the object. compareTo and equals must work correctly with subclasses. Comparison Operators and Objects of Different TypesWhen comparisons between different data types are supported, what happens when comparisons between objects when one of the types is orderable and the other is not? One of the Java Data Types is OrderableExpressions using the comparison operators are converted to internal Java expressions as shown in the following tables. If a is an orderable Java data type and b is an orderable or non-orderable Java data types: If a is not an orderable Java data type, but b is: Built-in data types are converted to their corresponding Java type before being used as parameters in the method calls shown in these tables. Neither Java Data Type Is Orderable(If neither Java Data Type is Orderable, only the = and <> operators are allowed.) If a is a non-orderable Java data type, the internal method calls are:
If a is a built-in type but b is a Java data type:
To force use of the specific method comparison (equals or compareTo), use the desired method call explicitly. For example: SELECT CITY FROM CITIES WHERE city.equals(?) NOTE: The JBMSTours sample application includes three orderable types. One is JBMSTours.serializabletypes.City. Look at this type if you want a concrete example. |
||||||||||||
|
![]() Cloudscape Version 3.6 For information about Cloudscape technical support, go to: www.cloudscape.com/support/.Copyright © 1998, 1999, 2000 Informix Software, Inc. All rights reserved. |