Package org.eclipse.birt.report.model.api

Tool-writer's interface for the BIRT design model (also known as the "Design Engine.")

See:
          Description

Interface Summary
CommandStack Application-level interface into the Model's command stack.
ErrorCodes Implements to define the error codes that are exposed to api.
IAbsoluteFontSizeValueProvider Provides the absolute dimension value for absolute font size constant.
IBundleFactory Retrieves resources in the Eclipse bundle.
IDesignConfig  
IDesignEngine Represents the BIRT design engine as a whole.
IDesignEngineFactory Factory class to create an instance of DesignEngine
IModuleOption Implements to define the keys to do some setting in a module.
IResourceLocator Implements this interface to provide a custom file search algorithm.
IVersionInfo Holds instrustions that inform the user if opening the old version design file may cause some auto-conversion to the original design file.
 

Class Summary
AccessControlHandle Describes the privilege to access resources.
ActionHandle Represents an "action" (hyperlink) attached to an element.
AggregationArgumentHandle AggregationArgumentHandle.
AutoTextHandle Represents a autotext report item.
BundleFactory The internal factory to find resources in the bundle.
CachedMetaDataHandle Structure handle to deal with cached data set metadata informations.
CascadingParameterGroupHandle Represents the group of cascading parameters.
CellHandle Represents a cell within a table or grid.
ColorHandle Handle to work with a color property.
ColumnBandData Represents the data structure to store copied objects like the column and cells.
ColumnHandle Represents a column within a table.
ColumnHintHandle Represents the handle of column hint.
ComplexValueHandle Abstract class for working with properties that have internal structure, such as a color, a dimension or a font.
ComputedColumnHandle Represents the handle of computed column.
ConfigVariableHandle Represents the handle of configuration variable.
ContentElementHandle  
CssSharedStyleHandle Css shared style handle.
CustomColorHandle Represents the handle of custom color.
DataGroupHandle  
DataItemHandle Represents a data item element.
DataSetHandle Abstract handle for data set elements.
DataSetParameterHandle Represents the parameter for data set drivers.
DataSourceHandle This abstract class represents a data source element: a connection to an external data provider such as an SQL database.
DefaultResourceLocator The default file search algorithm.
DesignConfig Wraps around configuration settings for design engine.
DesignElementHandle Base class for all report elements.
DesignEngine Represents the BIRT design engine as a whole.
DesignVisitor Applies logic customized to each type of report element.
DimensionConditionHandle Represents the handle of the cube-dimension/hierarchy join condition.
DimensionHandle Simplifies working with dimension properties.
DimensionJoinConditionHandle Represents a dimension join condition in the DimensionCondition.
ElementDetailHandle Abstract base class for property handles, slot handles, structure handles an other handles that provide detail about a report element.
ElementFactory Creates a new report elements and returns handles to it.
EmbeddedImageHandle Represents the handle of an embedded image.
EmptyGroupElementHandle Implements an empty group element handle, which actually can do nothing.
ErrorDetail Provides detail information about errors found when opening a design file.
ExtendedItemHandle Represents an extended element.
ExtendedPropertyHandle Represents the handle of Extended property.
FactoryPropertyHandle A specialized handle for use when creating the Factory data structures.
FilterConditionElementHandle  
FilterConditionHandle Represents one filter in the filter list of List, Table or their Groups.
FontHandle Simplifies working with the font family property.
FormatValueHandle Represents a format value in the style or the highlight rule.
FreeFormHandle Represents a free-form element.
GraphicMasterPageHandle Represents a graphic master page in the design.
GridColumnBandAdapter Represents an object of copied objects when do copy/paste operations between grids.
GridHandle Represents a grid item in the design.
GridRowBandAdapter Represents an object of copied objects when do copy/paste operations between grids.
GroupElementFactory This class is a factory class to instantiate a group element handle.
GroupElementHandle This class provides services to deal with a group of elements.
GroupHandle Represents both list and table groups in the design.
GroupPropertyHandle A handle for working with a top-level property of a collection of elements.
HideRuleHandle Represents the handle of visibility rule.
HighlightRuleHandle Represents a highlight rule in the highlight property of a style.
ImageHandle Represents an image report item.
IncludedCssStyleSheetHandle Represents a included css style sheet in report design and theme.
IncludedLibraryHandle Represents the handle of the included library.
IncludeScriptHandle Represents the handle of the included script.
JoinConditionHandle Represents a handle of condition used for joint dataset.
JointDataSetHandle Provides API to operate a joint data set.
LabelHandle Represents a label report item.
LevelAttributeHandle Represents the handle of one column in the result set.
LibraryHandle Represents the handle of library element.
LineHandle Represents the line item.
ListGroupHandle Represents a group in a list.
ListHandle Represents a list report item.
ListingHandle Represents slots and common properties in the two list-oriented elements: table and list.
MapRuleHandle Represents the handle of map rule.
MasterPageHandle Represents a master page.
MemberHandle A handle to a member of a property structure.
MemberIterator An iterator over the members of a structure.
MemberValueHandle CrosstabMemberValueHandle
ModelConstants Defines various constants.
ModuleHandle Abstract module handle which provides the common functionalities of report design and library.
ModuleOption Provide the way to do some setting about the module.
ModuleUtil Provides some tool methods about the modules.
MultiLineDataHandle Deprecated. by TextDataHandle
MultiViewsHandle Represents a multiple view element.
OdaDataSetHandle Represents an extended data set.
OdaDataSetParameterHandle Represents the parameter for ODA drivers.
OdaDataSourceHandle Represents a extended data source.
OdaDesignerStateHandle The structure handle of the Oda designer state.
OdaLevelAttributeHandle Represents the handle of one column in the oda result set.
OdaResultSetColumnHandle Represents the handle of one column in the oda result set.
ParamBindingHandle Represents the handle of parameter binding.
ParameterGroupHandle Represents a group of parameters.
ParameterHandle Represents the various parameter types.
PrivateStyleHandle Represents the "private style" for an element.
PropertyBindingHandle Represents the handle of property binding structure.
PropertyHandle A handle for working with a top-level property of an element.
PropertyMaskHandle Represents the handle of property mask structure.
RectangleHandle Represents a rectangle element.
ReportDesignHandle Represents the overall report design.
ReportElementHandle Abstract base class for working with all elements except the report design.
ReportItemHandle Represents a report item: any element that can appear within a section of the report.
ResultSetColumnHandle Represents the handle of one column in the result set.
RowBandAdapter Represents an object for copy/paste in Gird/Table.
RowBandInsertAction Does table row insert operation.
RowBandInsertAndPasteAction Does table row insert and paste operation.
RowBandPasteAction Does table row paste operation.
RowBandShiftAction Does table row shift operation.
RowHandle Represents one row in a Grid or Table.
RowOperationParameters Prepares parameters for row operation , including copy , paste , insert and shift operation.
RuleHandle Represents a rule handle.
ScalarParameterHandle Represents a scalar (single-value) report parameter.
ScriptDataSetHandle Represents a script data set item.
ScriptDataSourceHandle Represents a script data source.
ScriptLibHandle Represents a handle of jar file used for script handle event.
SearchKeyHandle Represents the handle of key used for search.
SelectionChoiceHandle Represents the handle of selection choice.
SessionHandle Represents the design state -- a session for a user.
SharedStyleHandle Represents a named, shared style.
SimpleGroupElementHandle Implements a simple group element handle, which has a non-empty selection element list and root module.
SimpleMasterPageHandle Represents a simple master page.
SimpleValueHandle Abstract base class that represents a handle for the value to either a property or a structure member.
SlotHandle Represents a "slot" within an element.
SlotIterator An Iterator over the elements in a slot.
SortedSlotIterator An sorted iterator over the elements in a slot.
SortElementHandle  
SortKeyHandle Represents the handle of sort key structure.
StructureFactory Provides the factory method to create empty structures.
StructureHandle Handle to a structure within a list property.
StyleHandle Represents the style properties for either a shared style or an element with a IStyleModel.
StyleRuleHandle Represents the handle of style rule.
TableColumnBandAdapter Represents an object of copied objects when do copy/paste operations between tables.
TableGroupHandle Represent a handle to a table group.
TableHandle Represents a table element.
TableRowBandAdapter Represents an object of copied objects when do copy/paste operations between tables.
TemplateDataSetHandle Handle for template data sets.
TemplateElementHandle Abstract handle for template elements.
TemplateParameterDefinitionHandle Represents a template parameter definition element.
TemplateReportItemHandle Handle for template report items.
TextDataHandle Represents a multi-line data item element.
TextItemHandle Represents a text data item.
ThemeHandle Represents a theme in the library.
TOCHandle Represents an "TOC" attached to an element.Obtain an instance of this class by calling the getTOCHandle method on the handle of an element that defines an action.
TranslationHandle Represents a translation message in the design.
UserPropertyDefnHandle Represents a top-level user-defined property of an element.
ValueAccessControlHandle Describes the privilege to access resources.
ValueHandle Abstract base class for value-based handles.
VariableElementHandle Represents a variable.
 

Exception Summary
DesignFileException Signals that a fatal error occurred when opening a design file.
IllegalOperationException Thrown to indicate that a method has been illegally called.
ModelException Implementation of BirtException in model project.
 

Package org.eclipse.birt.report.model.api Description

Tool-writer's interface for the BIRT design model (also known as the "Design Engine.")

This interface is not meant to be used by customer code "plugged into" the designer. The customer interface (to be defined) will be much more abstract and will not provide a way to access the model objects themselves. This interface is designed as a convenience for BIRT components that are aware of the model, but need a simple way to perform common operations.

Package Specification

The BIRT design model (Design Engine) performs a wide range of low-level tasks:

This API package isolates the GUI and Factory code from the details of the implemention by providing a series of handle classes. Clients of this API do not generally work the the actual model objects. Instead, clients work with API handles that provide higher-level services. For example, the handles provide "getter" and "setter" methods for each property of each report element. The model, however, stores properties as name/value pairs using an abstract representation.

The API encapsulates the complexity of the undo/redo system. While the "getter" methods are generally just light wrappers on top of the model; but the "setter" methods invoke the complex machinery needed to make changes in a way that is undoable and that notifies intersted listeners. For this reason, the application must make all changes via this API. Making changes directly to model objects will put the model into a state inconsistent with the undo/redo stack.

While the tool writer will often use this API, the tool writer is free to reach down into the lower layers when required for specialized tasks. For example, the property sheet will likely work directly with meta-data classes to obtain information about properties such as their type, available choices, and so on. While the application can query lower-level packages, all updates must be done though this API as explained above.

Using the API

The application uses the API as follows:

Higher-Level Operations

In addition to the detailed operations above, many handles provide additional higher-level operations. For example, operations exist to add a group to a listing, to change grouping order, and so on.

Note: Most high-level operations are not yet defined in the current version of the API.

Usage Notes

You should be aware of a number of special features of the API.

Working with Handles

There is a one-to-one correspondence between design elements and handles. Every design element can have 0 or 1 associated handle. The handle is created when first needed. Handles are immuatable: once created, they cannot point to a different element.

Working with Properties

Properties are a core part of the model. The API provides four distinct ways to work with properties. Choose the one that works best for the code you are writing.

Specific getter/setter.
The various element handles provide get and set methods for most properties. To avoid cluttering the interface with accessors for seldom-used properties, the API does not include accessors for every property. The set of properties exposed with specific methods will evolve based on the needs of tool writers.
Type-specific getter/setter.
If no specific getter/setter exists, or the application wishes to work with properties generically, then the application can use the type-specific methods such as DesignElementHandle.getIntProperty(java.lang.String), DesignElementHandle.getStringProperty(java.lang.String), etc. to get the property. Use DesignElementHandle.setIntProperty(java.lang.String, int), DesignElementHandle.setStringProperty(java.lang.String, java.lang.String), etc. to set the property. In each case, you specify the property name. See the element classes in the org.eclipse.birt.report.model.elements package for the set of properties available on each element.
As generic objects.
Properties are stored as objects internally. Some application code, such as a property sheet, may find it convenient to work with properties generically. Use the DesignElementHandle.getProperty(java.lang.String) and DesignElementHandle.setProperty(java.lang.String, java.lang.Object) method to do so.
Using property iterators and handles.
Finally, the API provides a set of iterators for traversing the set of properties for an element, and handles for working with each individual property. These classes are ideal for creating a generic property sheet driven by the set of properties defined for an element.

Many propeties are simple scalar values. However, quite a few have internal structure. For example, the highlight property provides a list of highlight rule structures. Dimension properties provide a CSS-format dimension such as "10in" or "20%". Specialized handles help parse such properties. Handles also exist for colors, fonts and others.

Property Inheritance

The vast majority of properties can be inherited. Such properties can be in one of two states: set or unset. A set property is one for which a given element has a value. An unset property is one for which an element does not explicitly have a value; instead the element inherits the value from its style or the element it extends. If the value is not set in either of these places, then the property assumes the default value for that property.

Property inheritance in BIRT is much like that in JavaScript. Both use prototype-based inheritance. As in JavaScript, BIRT enforces an asymmetry between getting and setting properties. Most getters will search for the property up the inheritance hierarchy as explained in the ROM specs. The setter changes the value only on the target element. Specializd getter methods exist that get only the local property value without doing a search.

BIRT also provides a set of properties called style properties. These properties support both JavaScript-like inheritance and CSS-like cascading. See the ROM spec for details.

The null value represents an unset property. It is thus important to understand the difference between, say, and empty string (the property is set and its value is "") and a null value (the property is unset.) Setting a property to a null value unsets the property for that element.

Property Types

BIRT supports a number of basic property types: String, Integer, Float (represented as a double) and Number (represented as a BigDecimal.) In adddition, BIRT uses a wide range of specialized types such as dimensions (discussed above), expressions, HTML, XML and so on. In general, BIRT will automatically convert any property to any of the basic types if the conversion is meaningful. For example, a choice property can be obtained as an integer (internal choice code) or string (choice name.)

Some properties are intrinsic -- they are stored as member variables in the implementation. Many such properties can be set or retrived in two ways: using the generic property mechanism, or specific get/set methods. For example, one can get the name using the NAME_PROP property name, or using the getName( ) method. The primary intrinsic properties are name, extends and style.

Internal and Display Property Values

When working with the string value of a property, the application must take care to differentiate between several forms:

Internal value
This is the value used within the application and in the XML design file. It is independent of the user's locale. It is often in a form convenient for scripting such as "if-empty".
Localized display value
This is a string translated to the user's own language. The value is locale-dependent; it will appear differently in English, Chinese or German. As a result, it is meaningful only in the current design session; it is translated into the internal value for persistent storage.
The applicaiton must be sure to call the correct method to get the value as either a display string or as an internal value. Similarly, distinct methods exist to set the internal value vs. the display value. In general, call DesignElementHandle.getStringProperty(java.lang.String) to get a localized property value and DesignElementHandle.setStringProperty(java.lang.String, java.lang.String) to set a localized property value. The API will perform any required translation. These calls work for all properties except lists.

Call DesignElementHandle.getStringProperty(java.lang.String) to get the internal value of a string property, and DesignElementHandle.setStringProperty(java.lang.String, java.lang.String) to set the internal value of a string property.

User-Defined Properties

The model supports user-defined properties. These are properties defined on an element by the user. Once defined, such properties work identically to system-defined properties. The above property rules, methods and classes for properties automatically include any user-defined properties. For example, the property iterator includes user-defined properties.

Dimensions

Dimensions give measurements within the report such as the size of a page, the (x,y) position of a report item, and so on. BIRT stores dimension properties using the CSS system: as a numeric measure and a string unit. The units can be absolute ("in", "cm") or relative ("em", "%"). As a result, the model cannot give the absolute size or position of a report element. Instead, the application must provide a CSS User Agent (UA) to compute the layout based on the dimension properties and element content. For example, a table may choose to be as wide as the page, to have three columns, and to allocate space in the ratio: 20%, 30% and 50%. Further the rows of the table may contain text, images, charts and other content. The UA is responsible for computing the layout based on the dimension properties, available fonts, actual image sizes and so on.

These calculations are done differently in the Designer UI than in the Presentation Engine. The Presentation Engine may leverage the end user's browser to do the layout (by passing the information in HTML), or may implement its own UA. The Designer UI will emulate a browser UA within the constraints of Eclipse.

The application must have a deep understanding of the CSS specification and the BIRT Report Object Model (ROM) to correctly interpret dimensions. (This may seem overly complex, but the alternative -- fixed sizes and positions -- leads to a report model that is easier to implement, but harder to use.)

Property Handles

Tools that work with properties may wish to use the various property handle classes.

Property iterators provide access to the set of properties defined on an element. The property sheet, for example, can use the iterator to learn about the complete set of properties.

Property handles provide an interface for working with a specific property.

Properties are defined in one of two ways. System properties are defined by the Report Object Model and are fixed from one design to the next. User-defined properties are created by the report developer (as explained above) and are stored as part of the report design.

System properties can be simple or structured. A simple property is a simple name/value pair such a name or a dimension. Structured properties represent a list of objects such as the mapping rules for a style. Property handles are required to work with structured properties. While the applicaiton can work directly with the structures to query existing information, the application must use the property handles to make changes.

Element Containment, Slots and Slot Handles

Many elements act as containers: they can hold other elements called content. For example, the report design has slots for data sources, data sets, styles, sections and more. Container have a slot for their contents. And so on.

The model uses slots to represent the containment relationship. When you call a method to work with the contents, the API returns a SlotHandle. Slot handles provide many operations imcluding adding, removing, moving and enumerating content.

Styles

Styles define the visual characteristics of report items. BIRT defines a set of standard styles that the report can customize. The report can add custom styles. Further, each element can override style properites for that one component.

Therefore, the same set of style properties appear on a wide array of elements. The application can work with style properties generically using any handle that represents either a style or an element with a style. If the application wants to work with specific getter/setter methods for style properties, it should obtain a StyleHandle.

There are two ways to obtain a style handle from an element. The first is to call DesignElementHandle.getStyle(). This method returns a SharedStyleHandle to the shared style (if any) that the element references. The other method is DesignElementHandle.getPrivateStyle(), which returns a StyleHandle to work with the style properties of that specific element. The two style handles provide the same set of getter and setter methods.

Related Documentation

The application developer should be familiar with the BIRT Report Object Model. See the following:



Copyright © 2008 Actuate Corp. All rights reserved.