org.eclipse.birt.report.model.api
Class DataSetHandle

java.lang.Object
  extended by org.eclipse.birt.report.model.api.DesignElementHandle
      extended by org.eclipse.birt.report.model.api.ReportElementHandle
          extended by org.eclipse.birt.report.model.api.DataSetHandle
All Implemented Interfaces:
org.eclipse.birt.report.model.elements.interfaces.IDataSetModel, org.eclipse.birt.report.model.elements.interfaces.IDesignElementModel, org.eclipse.birt.report.model.elements.interfaces.ISimpleDataSetModel
Direct Known Subclasses:
JointDataSetHandle, OdaDataSetHandle, ScriptDataSetHandle

public abstract class DataSetHandle
extends ReportElementHandle
implements org.eclipse.birt.report.model.elements.interfaces.IDataSetModel, org.eclipse.birt.report.model.elements.interfaces.ISimpleDataSetModel

Abstract handle for data set elements. A data set is a named object that provides a result set defined as a sequence of data rows. Report elements use data sets to retrieve data for display.

A data set has three key parts:

Data transforms that can be defined on a data set include:

The application can use scripts to execute code on certain data set events.

To get a handle for the data source, uses the following example:

 
 
                        DataSetHandle dataHandle = designHandle
                      findDataSet( "My First Data Set " );
 
 

This class works with the static design definition of the data set. Many clients will prefer to work with the TBD class that provides both the static definition and additional design information retrieved from the data provider. For example, a particular data set may not define a result set in the design file if the data provider can provide the result set definition itself. This handle will return null for the result set handle. However, the TBD class will provide the full result set: either by returning the one in the design file, or by obtaining it from the data provider.

See Also:
SimpleDataSet

Field Summary
 
Fields inherited from class org.eclipse.birt.report.model.api.ReportElementHandle
element
 
Fields inherited from class org.eclipse.birt.report.model.api.DesignElementHandle
module
 
Fields inherited from interface org.eclipse.birt.report.model.elements.interfaces.IDataSetModel
CACHED_METADATA_PROP, COLUMN_HINTS_PROP, COMPUTED_COLUMNS_PROP, FILTER_PROP, NEEDS_CACHE_PROP, PARAMETERS_PROP, RESULT_SET_HINTS_PROP, RESULT_SET_PROP, ROW_FETCH_LIMIT_PROP
 
Fields inherited from interface org.eclipse.birt.report.model.elements.interfaces.ISimpleDataSetModel
AFTER_CLOSE_METHOD, AFTER_OPEN_METHOD, BEFORE_CLOSE_METHOD, BEFORE_OPEN_METHOD, CACHED_ROW_COUNT_PROP, DATA_SET_ROW_LIMIT, DATA_SOURCE_PROP, ON_FETCH_METHOD, PARAM_BINDINGS_PROP
 
Fields inherited from interface org.eclipse.birt.report.model.elements.interfaces.IDesignElementModel
COMMENTS_PROP, CUSTOM_XML_PROP, DISPLAY_NAME_ID_PROP, DISPLAY_NAME_PROP, EVENT_HANDLER_CLASS_PROP, EXTENDS_PROP, FULL_LABEL, ID_SUFFIX, NAME_PROP, NO_SLOT, PROPERTY_MASKS_PROP, REF_TEMPLATE_PARAMETER_PROP, SHORT_LABEL, USER_LABEL, USER_PROPERTIES_PROP, VIEW_ACTION_PROP
 
Constructor Summary
DataSetHandle(org.eclipse.birt.report.model.core.Module module, org.eclipse.birt.report.model.core.DesignElement element)
          Constructs a data set handle with the given design and element.
 
Method Summary
 void addFilter(FilterCondition fc)
          Adds the filter condition.
 java.util.Iterator columnHintsIterator()
          Returns an iterator over column hints.
 java.util.Iterator computedColumnsIterator()
          Returns an iterator for the list of computed columns.
 java.util.Iterator filtersIterator()
          Returns an iterator over filter.
 java.lang.String getAfterClose()
          Returns the code of the afterClose method.
 java.lang.String getAfterOpen()
          Returns the code of the afterOpen method.
 java.lang.String getBeforeClose()
          Returns the code of the beforeClose method.
 java.lang.String getBeforeOpen()
          Returns the code of the beforeOpen method.
 CachedMetaDataHandle getCachedMetaDataHandle()
          Return a handle to deal with the cached data set information that include output column information when it gets from databases, input/output parameter definitions.
 int getCachedRowCount()
          Deprecated. by getDataSetRowLimit method
 int getDataSetRowLimit()
          Deprecated. duplicate with method getRowFetchLimit()
 DataSourceHandle getDataSource()
          Returns a handle to the data source for this data set.
 java.lang.String getDataSourceName()
          Returns the name of the data source for this data set.
 java.lang.String getOnFetch()
          Returns the code of the onFetch method.
 PropertyHandle getPropertyHandle(java.lang.String propName)
          Returns a property handle for a top-level property.
 int getRowFetchLimit()
          Returns the max number of rows from data set property value.
 boolean needsCache()
          Determines whether to do some cache when rendering the report.
 java.util.Iterator paramBindingsIterator()
          Returns an iterator over the list of parameter bindings.
 java.util.Iterator parametersIterator()
          Returns an iterator over the list of output parameter definitions.
 void removeFilter(FilterCondition fc)
          Removes the filter condition.
 java.util.Iterator resultSetHintsIterator()
          Returns an iterator over hints of the result set columns.
 java.util.Iterator resultSetIterator()
          Returns an iterator over the result set columns.
 void setAfterClose(java.lang.String code)
          Sets the code for the afterClose method.
 void setAfterOpen(java.lang.String code)
          Sets the code for the afterOpen method.
 void setBeforeClose(java.lang.String code)
          Sets the code for the beforeClose method.
 void setBeforeOpen(java.lang.String code)
          Sets the code for the beforeOpen method.
 CachedMetaDataHandle setCachedMetaData(CachedMetaData metadata)
          Set the value for the cached data set information.
 void setCachedRowCount(int count)
          Deprecated. by setDataSetRowLimit method
 void setDataSetRowLimit(int count)
          Deprecated. duplicate with method setRowFetchLimit()
 void setDataSource(java.lang.String name)
          Sets the name of the data source for this data set.
 void setNeedsCache(boolean needsCache)
          Sets whether to do some cache when rendering the report.
 void setOnFetch(java.lang.String code)
          Sets the code for the onFetch method.
 void setRowFetchLimit(int count)
          Sets the max number of rows from data set property value.
 
Methods inherited from class org.eclipse.birt.report.model.api.ReportElementHandle
getComments, getCustomXml, getDisplayName, getDisplayNameKey, getElement, getPropertyMask, isValidLayoutForCompoundElement, isValidReferenceForCompoundElement, propertyMaskIterator, setComments, setCustomXml, setDisplayName, setDisplayNameKey, setPropertyMask
 
Methods inherited from class org.eclipse.birt.report.model.api.DesignElementHandle
add, add, addElement, addElement, addListener, addUserPropertyDefn, cachePropertyHandles, canContain, canContain, canContain, canContain, canDrop, canEdit, canTransformToTemplate, clearAllProperties, clearContents, clearProperty, clientsIterator, copy, copyPropertyTo, createTemplateElement, derivedIterator, doSort, drop, drop, drop, dropAndClear, dropAndClear, dropAndClear, dropUserPropertyDefn, findContentSlot, getBooleanProperty, getChoices, getColorProperty, getContainer, getContainerPropertyHandle, getContainerSlotHandle, getContent, getContentCount, getContents, getDefn, getDesign, getDesignHandle, getDimensionProperty, getDisplayLabel, getDisplayLabel, getDisplayProperty, getEffectiveModule, getElementFactory, getElementProperty, getEventHandlerClass, getExtends, getExternalizedValue, getExternalizedValue, getExternalizedValue, getFactoryPropertyHandle, getFloatProperty, getFontProperty, getFullName, getHostViewHandle, getID, getIndex, getIntProperty, getListProperty, getListProperty, getMethods, getModule, getModuleHandle, getName, getNumberProperty, getPrivateStyle, getProperty, getPropertyBinding, getPropertyBindings, getPropertyDefn, getPropertyIterator, getQualifiedName, getRoot, getSemanticErrors, getSlot, getStringProperty, getStyle, getUserProperties, getUserPropertyDefnHandle, getXPath, hasLocalProperties, hasSemanticError, initializeSlotHandles, isDirectionRTL, isInTemplateParameter, isTemplateParameterValue, isValid, localize, move, move, moveTo, moveTo, moveTo, moveTo, paste, paste, paste, paste, removeListener, revertToReportItem, revertToTemplate, semanticCheck, setEncryption, setEventHandlerClass, setExtends, setExtendsElement, setExtendsName, setFloatProperty, setIntProperty, setName, setNumberProperty, setProperties, setProperty, setPropertyBinding, setStringProperty, setStyle, setStyleElement, setStyleName, setValid, shift, showError
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DataSetHandle

public DataSetHandle(org.eclipse.birt.report.model.core.Module module,
                     org.eclipse.birt.report.model.core.DesignElement element)
Constructs a data set handle with the given design and element. The application generally does not create handles directly. Instead, it uses one of the navigation methods available on other element handles.

Parameters:
module - the module
element - the model representation of the element
Method Detail

getDataSource

public DataSourceHandle getDataSource()
Returns a handle to the data source for this data set.

Returns:
handle to the data source, or null if the data source is not set or is undefined.

getDataSourceName

public java.lang.String getDataSourceName()
Returns the name of the data source for this data set.

Returns:
the data source name as a string
See Also:
setDataSource(String)

setDataSource

public void setDataSource(java.lang.String name)
                   throws SemanticException
Sets the name of the data source for this data set. This method checks whether the data source name exists in the report design.

Parameters:
name - the data source name
Throws:
SemanticException - if the data source does not exist in the report design, or the property if locked.
See Also:
getDataSource()

parametersIterator

public java.util.Iterator parametersIterator()
Returns an iterator over the list of output parameter definitions. The iterator returns instances of DataSetParameterHandle that represents parameter objects.

Returns:
iterator over output parameter definitions.
See Also:
DataSetParameter

paramBindingsIterator

public java.util.Iterator paramBindingsIterator()
Returns an iterator over the list of parameter bindings. The iterator returns instances of ParamBindingHandle that represents parameter binding object.

Returns:
iterator over parameter binding.
See Also:
ParamBinding

resultSetIterator

public java.util.Iterator resultSetIterator()
Returns an iterator over the result set columns. The iterator returns instances of ResultSetColumnHandle that represents result set column object.

Returns:
iterator over result set columns.
See Also:
ResultSetColumn

resultSetHintsIterator

public java.util.Iterator resultSetHintsIterator()
Returns an iterator over hints of the result set columns. The iterator returns instances of ResultSetColumnHandle that represents hints of result set column object.

Returns:
iterator over hints of result set columns.
See Also:
ResultSetColumn

computedColumnsIterator

public java.util.Iterator computedColumnsIterator()
Returns an iterator for the list of computed columns. The iterator returns instances of ComputedColumnHandle that represents computed column object.

Returns:
iterator over computed columns.
See Also:
ComputedColumn

columnHintsIterator

public java.util.Iterator columnHintsIterator()
Returns an iterator over column hints. The iterator returns instances of ColumnHintHandle that represents column hint object.

Returns:
iterator over column hints.
See Also:
ColumnHint

filtersIterator

public java.util.Iterator filtersIterator()
Returns an iterator over filter. The iterator returns instances of FilterConditionHandle that represents filter condition object.

Returns:
iterator over filters.
See Also:
FilterCondition

getBeforeOpen

public java.lang.String getBeforeOpen()
Returns the code of the beforeOpen method. This is the script called just before opening this data set.

Returns:
the code of the method

setBeforeOpen

public void setBeforeOpen(java.lang.String code)
                   throws SemanticException
Sets the code for the beforeOpen method. This is the script called just before opening this data set.

Parameters:
code - the code for the method
Throws:
SemanticException - If the method is locked.

getBeforeClose

public java.lang.String getBeforeClose()
Returns the code of the beforeClose method. This is the script called just before closing this data set.

Returns:
the code of the method

setBeforeClose

public void setBeforeClose(java.lang.String code)
                    throws SemanticException
Sets the code for the beforeClose method. This is the script called just before closing this data set.

Parameters:
code - the code for the method
Throws:
SemanticException - If the method is locked.

getAfterOpen

public java.lang.String getAfterOpen()
Returns the code of the afterOpen method. This is the script called just after opening this data set.

Returns:
the code of the method

setAfterOpen

public void setAfterOpen(java.lang.String code)
                  throws SemanticException
Sets the code for the afterOpen method. This is the script called just after opening this data set.

Parameters:
code - the code for the method
Throws:
SemanticException - If the method is locked.

getAfterClose

public java.lang.String getAfterClose()
Returns the code of the afterClose method. This is the script called just after closing this data set.

Returns:
the code of the method

setAfterClose

public void setAfterClose(java.lang.String code)
                   throws SemanticException
Sets the code for the afterClose method. This is the script called just after closing this data set.

Parameters:
code - the code for the method
Throws:
SemanticException - If the method is locked.

getOnFetch

public java.lang.String getOnFetch()
Returns the code of the onFetch method. This is the script called just after fetching each row.

Returns:
the code of the method

setOnFetch

public void setOnFetch(java.lang.String code)
                throws SemanticException
Sets the code for the onFetch method. This is the script called just after fetching each row.

Parameters:
code - the code for the method
Throws:
SemanticException - If the method is locked.

getCachedMetaDataHandle

public CachedMetaDataHandle getCachedMetaDataHandle()
Return a handle to deal with the cached data set information that include output column information when it gets from databases, input/output parameter definitions.

Returns:
a CachedMetaDataHandle to deal with the cached data set information, return null if the property has not been set.

setCachedMetaData

public CachedMetaDataHandle setCachedMetaData(CachedMetaData metadata)
                                       throws SemanticException
Set the value for the cached data set information.

Parameters:
metadata - a structure value include output column information , input/output parameter definitions.
Returns:
CachedMetaDataHandle to the input metadata, return null if metadata is null.
Throws:
SemanticException - the input data is not valid.

getPropertyHandle

public PropertyHandle getPropertyHandle(java.lang.String propName)
Description copied from class: DesignElementHandle
Returns a property handle for a top-level property. A top-level property is a property that defines on an element.

Overrides:
getPropertyHandle in class DesignElementHandle
Parameters:
propName - the name of the property to get
Returns:
The property handle, or null if the no property exists with the given name.
See Also:
PropertyHandle

setDataSetRowLimit

public void setDataSetRowLimit(int count)
                        throws SemanticException
Deprecated. duplicate with method setRowFetchLimit()

Sets data set row limit property value.

Parameters:
count -
Throws:
SemanticException

getDataSetRowLimit

public int getDataSetRowLimit()
Deprecated. duplicate with method getRowFetchLimit()

Returns value of data set row limit property.

Returns:

setCachedRowCount

public void setCachedRowCount(int count)
                       throws SemanticException
Deprecated. by setDataSetRowLimit method

sets the cached row count property value.

Parameters:
count - the cached row count
Throws:
SemanticException

getCachedRowCount

public int getCachedRowCount()
Deprecated. by getDataSetRowLimit method

Returns the value of cached row count property.

Returns:
the row count.

setRowFetchLimit

public void setRowFetchLimit(int count)
                      throws SemanticException
Sets the max number of rows from data set property value.

Parameters:
count - the row number to fetch from result set
Throws:
SemanticException

getRowFetchLimit

public int getRowFetchLimit()
Returns the max number of rows from data set property value.

Returns:
the max number of rows that can be fetched from data set.

addFilter

public void addFilter(FilterCondition fc)
               throws SemanticException
Adds the filter condition.

Parameters:
fc - the filter condition structure
Throws:
SemanticException - if the expression of filter condition is empty or null

removeFilter

public void removeFilter(FilterCondition fc)
                  throws SemanticException
Removes the filter condition.

Parameters:
fc - the filter condition structure
Throws:
SemanticException - if the given condition doesn't exist in the filters

setNeedsCache

public void setNeedsCache(boolean needsCache)
                   throws SemanticException
Sets whether to do some cache when rendering the report.

Parameters:
needsCache - true if needs do caching when rendering the report, otherwise false
Throws:
SemanticException

needsCache

public boolean needsCache()
Determines whether to do some cache when rendering the report.

Returns:
true if needs do caching when rendering the report, otherwise false


Copyright © 2008 Actuate Corp. All rights reserved.