BIRT, Design API and rptLibrary

The BIRT Design Engine API (DEAPI) provides the Java developers added flexibility to create, explore or modify BIRT report designs programmatically. For example, the BIRT Designer is built using this API. To use the DEAPI in your application, you’ll need the design engine SDK. More detailed information are available on the BIRT website.
For example let’s try to move a table column on a design using the DEAPI in a RCP (or RAP) application.

First, create an instance of the design engine and get a SessionHandle.

1. IDesignEngineFactory designEngineFactory = (IDesignEngineFactory) Platform
2. .createFactoryObject(IDesignEngineFactory.EXTENSION_DESIGN_ENGINE_FACTORY);
3. IDesignEngine designEngine = designEngineFactory .createDesignEngine(new DesignConfig());
4. SessionHandle session = designEngine.newSessionHandle(null);

Then, open the desired report design.

1. ReportDesignHandle designHandle = session.openDesign(“sample.rptDesign”);

Next, retrieve the table and the columns to move thanks to their design id.

1. TableHandle table = (TableHandle) findElementHandle(designHandle.getBody(), tableDesignId);
2. int sourceColIndex = ((ColumnHandle) findElementHandle(table.getColumns(), sourceColDesignId)).getIndex();
3. int destinationColIndex = ((ColumnHandle) findElementHandle(table.getColumns(), destinationColDesignId)).getIndex();

Where :

1. private static DesignElementHandle findElementHandle(SlotHandle slotHandle, long designId) {
2. // search into the slot content for the element corresponding to the given design id
3. for (DesignElementHandle elementHandle : (List<DesignElementHandle>) slotHandle.getContents()) {
4. // if found at this level, return it
5. if (elementHandle .getID() == designId) {
6. return elementHandle ;
7. }
8. // else do the same recursively in its children
9. else {
10. int elementSlotCount = element.getDefn().getSlotCount();
11. for (int i = 0; i < elementSlotCount ; i++) {
12. DesignElementHandle handle = findElementHandle(element.getSlot(i), designId);
13. if (handle != null) {
14. return handle;
15. }
16. }
17. }
18. }
19. return null;
20. }

Finally, call the appropriate given method on these elements :

1. if (sourceColIndex > destColumnIndex) {
2. table.shiftColumn(sourceColIndex + 1, destinationColIndex);
3. }
4. else {
5. table.shiftColumn(sourceColIndex + 1, destinationColIndex + 1);
6. }

The report design can be ran and rendered again to verify the modification. It can also be save and close to persist it.

1. designHandle.save();
2. designHandle.close();

BIRT allow developers to store and share design elements thanks to a report library. So as designs, libraries can be manipulated via the DEAPI. But what will happen if a design composed of elements from a Library is trying to be altered by the DEAPI ?
Let’s imagine that our Table is now an extension of a referenced report library :

<table name="Table" id="10" extends="library.Library_Table">

Executing the same code as described previously will lead to the following error :

 org.eclipse.birt.report.model.api.elements.SemanticError: The paste operation on the element "Table" is forbidden.    at org.eclipse.birt.report.model.api.ColumnBandShiftAction.shiftColumnBand(ColumnBandShiftAction.java:155)    at org.eclipse.birt.report.model.api.TableHandle.shiftColumn(TableHandle.java:556)

Indeed, as the table is inherited from the library, it can’t be modified when the DEAPI is working on the report design. This change can only be applied on the report library itself. This behavior can be a restrictive argument to develop an application which is changing dynamically design, like an interactive viewer… At least, it prevents from using library…
One idea to avoid this is to copy the extended elements from the library to the design while opening it, always thanks to DEAPI.

1. /* retrieve report libraries and put them in a map by namespace */
2. Map<String, LibraryHandle> libraries = new HashMap<String, LibraryHandle>();
3. for (LibraryHandle library : (List<LibraryHandle>) designHandle.getLibraries()) {
4. libraries.put(library.getNamespace(), library);
5. }
6. replaceExtendsElementHandle(designHandle.getBody(), libraries);

Where :

1. private static void replaceExtendsElementHandle(SlotHandle slotHandle,
2. Map<String, LibraryHandle> libraries) throws SemanticException {
3. /* iterates over slot content to find an extend element */
4. for (int i = 0; i < slot.getCount(); i++) {
5. DesignElementHandle elementHandle = slotHandle.get(i);
6. ElementRefValue extendsRefValue = (ElementRefValue) elementHandle.getElement().
7. getLocalProperty(elementHandle.getModule(), IDesignElementModel.EXTENDS_PROP);
8. /* if not null drop and copy */
9. if (extendsRefValue != null) {
10. slotHandle.drop(i);
11. slotHandle.add(libraries.get(extendsRefValue.getLibraryNamespace()).
12. findElement(elementHandle.getName()), i);
13. }
14. // else search into its children for extend element
15. else {
16. int slotCount = elementHandle.getDefn().getSlotCount();
17. for (int j = 0; j < slotCount; j++) {
18. replaceExtendsElementHandle(elementHandle.getSlot(j), libraries);
19. }
20. }
21. }
22. }

But if you execute this code, the following error will occur :

 org.eclipse.birt.report.model.api.IllegalOperationException: The module is read-only and operation is forbidden.

The last trick to finally obtain the wanted result is to take a copy of the declared library :

1. for (LibraryHandle library : (List<LibraryHandle>) designHandle.getLibraries()) {
2. libraries.put(library.getNamespace(), (LibraryHandle) library.copy().
3. getHandle(library.getModule()));
4. }

I want to thanks the BIRT newsgroup and more precisely Jason for helping me while working on this case.