6.2 Binary Compatibility

The standard enhancement interface defined by the JDO reference-enhancement contract provides binary compatibility among all enhancers and runtime environments. It requires that:

• A class enhanced by the reference enhancer is usable with any JDO-compliant runtime environment.

• A class enhanced by a JDO-compliant vendor's enhancer is usable by the reference implementation's runtime environment.

• A class enhanced by a JDO-compliant vendor's enhancer is usable by any other JDO-compliant runtime environment.

Furthermore, an enhanced class file can be shared concurrently in a JVM among several coresident JDO implementations.

An implementation's runtime environment can determine whether a class was enhanced by its own enhancer. If it has, the implementation's runtime environment can use any implementation-specific enhancements that were placed in the class file. Otherwise, it must use the standard reference-enhancement interface contract. Table 6-1 shows which enhancement interface a JDO runtime environment will use, based on the enhancer used to enhance the class.

Table 6-1. Enhancement interfaces used

Enhancer used	Reference runtime	Vendor A runtime	Vendor B runtime
Reference enhancer	Reference enhancement	Reference enhancement	Reference enhancement
Vendor A enhancer	Reference enhancement	Vendor A enhancement	Reference enhancement
Vendor B enhancer	Reference enhancement	Reference enhancement	Vendor B enhancement

You can distribute your classes in either their enhanced or unenhanced form. Both forms are portable across implementations. If you are distributing the classes as a third-party class library that will be used in a variety of applications, you probably should distribute them unenhanced. The developers using your classes can then choose which enhancer to use. In this case, we recommend you provide them with the necessary metadata for your classes, which they may need to customize. If you are deploying an application that uses a specific JDO implementation, you may distribute your persistent classes in their enhanced form. It does not matter though, because a class distributed in its enhanced form can still be used with any JDO-compliant implementation. If you expect your classes will be used with multiple JDO implementations and you wish to distribute them in their enhanced form, we recommend that you use the Sun reference enhancer.