Package org.eclipse.birt.report.model.api
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)
, etc. to get the property. UseDesignElementHandle.getStringProperty(java.lang.String)
,DesignElementHandle.setIntProperty(java.lang.String, int)
, etc. to set the property. In each case, you specify the property name. See the element classes in theDesignElementHandle.setStringProperty(java.lang.String, java.lang.String)
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
andDesignElementHandle.getProperty(java.lang.String)
method to do so.DesignElementHandle.setProperty(java.lang.String, java.lang.Object)
- 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.
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
.
This method returns a
DesignElementHandle.getStyle()
to the shared style
(if any) that the element references. The other method is
SharedStyleHandle
, which returns a
DesignElementHandle.getPrivateStyle()
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.
-
Interface Summary Interface Description 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 DesignEngineIModuleOption Implements to define the keys to do some setting in a module.IResourceLocator Implements this interface to provide a custom file search algorithm.IResourceLocatorBase 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 Class Description AbstractMultiViewsHandle Represents a multiple view element.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.CellContextInfo Represents the context information of a cell The information includes the container of the row where the cell resides, the slot id, the group id , the row number, the row span, the column span and the "drop" property in the slot.CellHandle Represents a cell within a table or grid.ClientIterator Iterates over the clients of an element.ColorHandle Handle to work with a color property.ColumnBandAction Provides the fundmental operations to column band operations such as: copy/paste, shift a column band, etc.ColumnBandAdapter Represents an object for copy/paste in Gird/Table.ColumnBandCopyAction Provides the copy operation to the column band in the grid/table.ColumnBandData Represents the data structure to store copied objects like the column and cells.ColumnBandInsertAction Provides the insert and paste operation to the column band in the grid/table.ColumnBandInsertPasteAction Provides the insert and paste operation to the column band in the grid/table.ColumnBandPasteAction Provides the paste operation to the column band in the grid/table.ColumnBandShiftAction The action to shift one column from one position to another in the same Table/Grid.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.ComputedValueHandler Represents the handler which processes the computed length value as CSS specification describes.ConfigVariableHandle Represents the handle of configuration variable.ContentElementHandle CSSLengthValueHandler Represents the handler which computes the length value as CSS specification describes.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.DataSetHandle.DataSetParametersPropertyHandle Represents the property handle which handles the structure list of data set parameters.DataSetParameterHandle Represents the parameter for data set drivers.DataSetParameterHandle.NameMemberHandle Represents the member handle which handles the "name" member in the data set parameter structure.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 interfaceIResourceLocator
.DerivedDataSetHandle Provides API to operate a derived data set.DerivedElementIterator An iterator over the children of an element.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.DesignVisitorImpl 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.ElementFactoryImpl 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.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.ExtendedPropertyHelper The helper class forOdaDataSourceHandle
andOdaDataSetHandle
.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.FontSizeValueHandler Represents the handler which processes the font size computation as CSS specification describes.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.LayoutModuleHandle Abstract module handle which provides the common functionalities of report design and library.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 CrosstabMemberValueHandleModelConstants Defines various constants.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. MultiViewsAPIProvider Implements functions to deal with API-level views operations.MultiViewsElementProvider Implements functions to deal with functions for multiple-views element.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.PropertyIterator An iterator over the properties defined for an element.PropertyMaskHandle Represents the handle of property mask structure.RectangleHandle Represents a rectangle element.ReportDesignHandle Represents the overall report design.ReportDesignHandleImpl 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 ReportItemThemeHandle Represents a report item theme in the library.ResultSetColumnHandle Represents the handle of one column in the result set.RowBandAction Abstract class that shared by copy , paste , shift , insert operation.RowBandAdapter Represents an object for copy/paste in Gird/Table.RowBandCopyAction Does table row copy operation.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.SessionHandleImpl 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.SimpleIterator Iterates over the items within a property or member defined as a list of simple value.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.StructureIterator Iterates over the structures within a property or member defined as a list of structures.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 thegetTOCHandle
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. -
Exception Summary Exception Description 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.