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

package org.eclipse.birt.report.model.api
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:

- Read and write design files.
- Maintain the command history for undo/redo.
- Provide a rich semantic representation of the report design.
- Provide meta-data about the Report Object Model.
- Perform property value validation.
- Notify the application when the model changes.

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:

- Start by using the `DesignEngine` class to create a new design sesion. Specify the user's locale, or use the default locale. Then, use the design session to create or open an existing design from a file.
- When the application creates or opens a design, it receives an `ReportDesignHandle` instance. This handle represents the overall report design. The application can have any number of report designs open concurrently. Use methods on this handle to save the design to a file, and to access the command stack for undo and redo.
- Use other methods on the report design handle to navigate to the various parts of the report. The design provides a number of slots that contain elements. For example, the Data Source slot contains the design's data sources, the Body slot contains the sections, and so on.
- Each report element has its own handle type. The application can perform many generic tasks using the base `DesignElementHandle` class. Cast the handle to a specific subclass to work with the operations unique to that report element.
- The application creates elements using a two-step process. First, the application uses the `ElementFactory` class to create the new element. Then, the application adds the element to the design by inserting them into a slot of another element.
- A series of properties give the state of each element. Properties are defined using the `org.eclipse.birt.report.model.metadata` meta-data package. The application can get and set properties generically using the property names. Or, the application can use the specific getter/setter methods on the various specialized handles.
- The application can also work with a variety of property handle classes to perform specialized tasks, to work with multiple items at one time, and so on.

## 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:

- The BIRT design XML schema.
- The BIRT Report Object Model specifications.
- The `DesignElement` class for details on the services that the model offers.
- The `MetaDataDictionary` class for information about element, type, property, structure and member definitions.

Related Packages
Package
Description
org.eclipse.birt.report.model.api.activity
Manages the low-level undoable operations and event notifications.
org.eclipse.birt.report.model.api.command
Provides events when some command operations modify the state of the Design Engine.
org.eclipse.birt.report.model.api.core
Represents the fundamental data structures of the user-defined property and the interface of UI listener.
org.eclipse.birt.report.model.api.css
org.eclipse.birt.report.model.api.elements
Constants definition for the pre-defined choices and report elements and items.
org.eclipse.birt.report.model.api.extension
Defines the fundamental interfaces for those extensions from the reportitem extension point.
org.eclipse.birt.report.model.api.filterExtension
org.eclipse.birt.report.model.api.impl
org.eclipse.birt.report.model.api.metadata
Defines the elements, properties, types, structures and slots in the Report Object Model.
org.eclipse.birt.report.model.api.oda
org.eclipse.birt.report.model.api.olap
org.eclipse.birt.report.model.api.scripts
org.eclipse.birt.report.model.api.simpleapi
Report element representations in the BIRT simple API environment.
org.eclipse.birt.report.model.api.util
Utility classes.
org.eclipse.birt.report.model.api.validators
Provides the validation classes for semantic check on multiple properties.
Class
Description
AbstractScalarParameterHandle
Represents the abstract scalar parameter types.
AbstractScalarParameterHandleImpl
Represents the abstract scalar parameter types.
AbstractThemeHandle
Represents a abstract theme in the library.
AccessControlHandle
Deprecated.
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.
CalculationArgumentHandle
CalculationArgumentHandle.
CascadingParameterGroupHandle
Represents the group of cascading parameters.
CascadingParameterGroupHandleImpl
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.
CommandStack
Application-level interface into the Model's command stack.
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 implementation for interface `IResourceLocator`.
DerivedDataSetHandle
Provides API to operate a derived data set.
DesignConfig
Wraps around configuration settings for design engine.
DesignElementHandle
Base class for all report elements.
DesignEngine
Represents the BIRT design engine as a whole.
DesignFileException
Signals that a fatal error occurred when opening a design file.
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.
DynamicFilterParameterHandle
Represents the dynamic filter parameter types.
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.
ErrorCodes
Implements to define the error codes that are exposed to api.
ErrorDetail
Provides detail information about errors found when opening a design file.
Expression
Represents the object for the expression.
ExpressionHandle
Simplifies working with expression properties.
ExpressionListHandle
Simplifies working with expression lists.
ExpressionType
Enumerates the expression types.
ExtendedItemHandle
Represents an extended element.
ExtendedPropertyHandle
Represents the handle of Extended property.
FactoryElementHandle
Factory element handle class to retrieve some factory styles.
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.
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
IllegalOperationException
Thrown to indicate that a method has been illegally called.
ImageHandle
Represents an image report item.
IModuleOption
Implements to define the keys to do some setting in a module.
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.
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.
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.
LibraryHandleImpl
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.
ModelException
Implementation of BirtException in model project.
ModuleHandle
Abstract module handle which provides the common functionalities of report design and library.
ModuleHandleImpl
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.
PropertyHandleImpl
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.
ReportItemHandleImpl
Abstract implementation class for the report item handle
ReportItemThemeHandle
Represents a report item theme in the library.
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
SortHintHandle
This class represents sort hint handle.
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.
TimeIntervalHandle
The structure handle of time interval.
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
Deprecated.
ValueHandle
Abstract base class for value-based handles.
VariableElementHandle
Represents a variable.