Working with Native Peers

The high-level API of JExcel provides functionality to perform a number of the most common actions easily. But the functionality of JExcel is not limited by the high-level wrappers - a number of non-trivial actions can be done with the native peers.

Native peers can be considered as more direct Java wrappers for the Excel object model - that is the same object model that is available in VBA. That means if there is an approach to implement some functionality in VBA, it is likely that the similar approach can be implemented and will work in JExcel. Moreover, the documentation for the Excel object model can be used to work with the methods available in the native peers.

The native peers were created to be compatible with several versions of Microsoft Excel, and some properties or methods which were added in the latest versions of Excel may not be available through native peers directly. This does not mean that all the newest functionality is inaccessible in JExcel - it is still possible to access it via Automation.

Excel COM server works in STA. In general, that means the native peers are not thread-safe, and that's why all the calls to their methods are performed using the corresponding OleMessageLoop, which marshals the calls to the proper thread. The high-level JExcel API ( like Application, Workbook, Worksheet, Range and Cell classes) is designed to hide all this marshaling logic and perform parameters wrapping properly. As a result, each single call to the high-level API implies synchronization by the OleMessageLoop.

The best practice is to release the native peer objects that were obtained as soon as the application does not need them anymore. This should be done in the thread where they were obtained. Do not perform manual release for the native peer objects that are already bound to the JExcel high-level wrappers (Application, Workbook, Worksheet, Range, Cell, or Window) - those native peers should be released through their high-level wrappers only.