*** This interface is subject to change. ***

com.sas.iquery.metadata.business
Interface BusinessQuery

All Superinterfaces:

java.util.EventListener, com.sas.iquery.intelligentquery.IntelligentQueryInterface, PropertyChangeListenee, java.beans.PropertyChangeListener

All Known Subinterfaces:

DataSelection

public interface BusinessQuery
extends com.sas.iquery.intelligentquery.IntelligentQueryInterface, java.beans.PropertyChangeListener, PropertyChangeListenee

Specifies the interface that models the information that is necessary to request a result set based on business items that are contained in business models that are managed by the Intelligent Query Metadata Service. The BusinessQuery helps define and manipulate a query based on business metadata. It supports multiple views and the ability to let each view be notified when the model changes.

Relational sorting of data items

Sort Direction

To specify how a particular data item's values are to be sorted, one may specify the sort direction for the data item. The sort direction attribute for a DataItemReference is inherited from its parent (base) data item if it is not explicitly set (overridden) in the DataItemReference.

Sort Order Precedence

To specify the precedence order of the data items to be sorted on, one may specify the "sort order precedence" list of data items for a business query.

OLAP Sorting for a business query

Sorting is applied to either a data item or a business query. Sorting is applied to the data item using methods in the DataItem class.

The sort criteria is defined for a data item is based either on the value of category data item label or the value of a measure defined in the definition of that category.

The sort criteria is defined for a business query is based on the value of a measure in the crossing of a set or tuples (which would generate a MDX phrase:

 CROSSJOIN({[TIME].[YEAR].MEMBERS}, {[GEOGRAPHIC].[COUNTRY].MEMBERS}),  [Measures].[ACTUAL_AVG], DESC) ) ON ROWS.
 

This type of sort would be achieved by defining the following:

 List sortCriteria = new ArrayList();
 String[]  measures = { measure };<<== where name is [ACTUAL_AVG]
 sortCriteria.put(measures);
 businessQuery.setSortCriteria(sortCriteria,com.sas.iquery.metadata.business.Role.ROW)
 businessQuery.setSortDirection(BusinessQueryActionType.SORT_HIERARCHY_DESCENDING, com.sas.iquery.metadata.business.Role.ROW);

If sorting has been defined for both a data item and a business query, both will be honored if the BusinessQueryProperty.BUSINESS_QUERY_OLAP_SORT_PRECEDENCE property has been set to FALSE. If we applied the following:

businessQuery.setQueryProperty(BusinessQueryProperty.BUSINESS_QUERY_OLAP_SORT_PRECEDENCE, true);

then, we would generate a MDX phrase:

 generate ( ORDER([TIME].[YEAR].MEMBERS, [TIME].CURRENTMEMBER.NAME, bdesc),
 CrossJoin ( {[TIME].CURRENTMEMBER  },
 order( [GEOGRAPHIC].[COUNTRY].MEMBERS, [Measures].[ACTUAL_SUM],BDESC) ) )
 

OLAP Filtering for a business query

Business Query can be filtered by a particular value threshold in a measure, a particular value range or list in a catergory, or a particular ranking of value in a measure. This filtering is performed by applying steps to a business query. To determine out how steps can be applied to a business query for OLAP filtering and ranking, see com.sas.iquery.metadata.business.step.

OLAP Totaling

One can look at total in two different modes:

• Visual Value

Visual Value is is a sum of all the members at a given level which actually appear in the result set.

• Cube Value

A cube value is the standard aggregate value for a given member as returned by the server, if the user has access to these members.

Totals can be applied on one of the two modes in one of the following defintions:

• Subtotal

A subtotal is the value for a parent (see "Parent values") that has been added to the output because the user has asked for subtotals. It can therefore be either a Visual Total or a Cube Value.

• Row Total, Column Total

Row Total and Column Total occurs at the outermost hierarchy and level in the result set on either the column axis or the row axis.

Column totals are displayed as the last/first row(s) on the row axis. Row totals are displayed as the last/first column(s) on the column axis. When a total is coalesced, there is a single row/column for total. If total is not coalesced, you will see the natural multidimensional presentation.

• Grand Total

This is the visual total or cube value on the bottom right (or top left) of a grid. This is naturally presented as the cell where Row Total and Column Total intersect. Note: There may be more than one grand total as there may be more than one measure.

Totals can be applied as coalesced or not coalesced. Coalesced means where most crossings with non-leaf members on outer dimensions are removed. Specifically, the rule for removing crossings is: For each outer dimension on an axis, starting with the outermost dimension and working in, remove crossings with that dimension's non-leaf members. The exception is where the member for the dimension nested within the current dimension is the common ancestor of all other members in that dimension (an example of this would be the All Member). If there is no member that is the common ancestor, remove no crossings.

• Parent Values

A parent value is the value for an item that appears along with one or more of its children. Note that the value a user sees may not include all children, if security is set so that a user does not have access to all of the children, or if the query contains a filter and the user has asked for "visual total" instead of "cube value". Note that an item may or may not be a "parent" depending on context. For example, if Southeast occurs along with North Carolina, it is a parent, but if it occurs with Wake County (a grandchild) it is not. Parent values can occur either when the query contains a filter or when the user has asked for subtotals. They cannot be created just by doing an Expand or a Drill.

• Non-Additive and Non-Aggregable value

The total and subtotal should inherit the inherent statistic of the current measure in the same way as the AGGREGATE function. This means that measures which are non-additive should be computed in accordance with the appropriate semantics for the various statistics: AVG, MIN, MAX, etc.

There are some aggregations which do not fit into the totaling mode. For example: an aggregation across the measure dimension.

• All Member

The all member is the parent of the highest level nodes in a cube. For example, if continents form the top of a Geography hierarchy, the all member would give the sum of everything in the entire world.

The type of totaling that can be applied are:

• ALLTOTAL - applies subtotaling and grandtotaling to all dimensions, their members, and their levels for a Row or Column to an OLAP business model. *

  To define this type of totaling, use the following:

  dataSelection.setTotalType(bq.ALLTOTAL, Role.ROW);<<-- for all totaling on row.

• SUBTOTAL - applies sub-totals to all innermost dimensions, their members, a nd their levels for a Row or Column to an OLAP business model. *

  To define this type of totaling, use the following:

  dataSelection.setTotalType(bq.SUBTOTAL, Role.ROW);<<-- for sub totaling on row.

• AXISTOTAL - applies totals to outmost dimension and the all member for Row or Column axis.

  To define this type of totaling, use the following:

  dataSelection.setTotalType(bq.AXISTOTAL, Role.ROW);<<-- for grand totaling on row. axis

• TOTAL_NONE - deactivates any totals that have been applied to a relational or OLAP business model. *

  To define this type of totaling, use the following:

  dataSelection.setTotalType(bq.TOTAL_NONE, Role.ROW);<<-- for no totaling on the row.

Note: What happens if the All member of a dimension is excluded by the Permission condition?

Each dimension has a default member. That member is implicitly being used if no other members of that dimension are explicitly selected in your query. Usually the All member of a dimension is also the default member. If you remove the All member by not including it in the Permission Condition, the default member becomes the first member of the set specified in the Permission Condition.

Unless otherwise noted, all getter/setter method pairs do not copy their outputs or inputs, respectively. That is, if one calls the setter method and immediately calls the getter method for that same attribute, the object that was just given on the setter method will be returned by the getter. The only general exception to this rule, which is not documented further on the getter/setter methods, is when the output or input is a List, in which case the List is copied but the contents of the list are not copied. (A shallow copy of the List is made in both the setter and getter methods).

Field Summary

static java.lang.String	ALLTOTAL This totaling action defines that both subtotals and axistotals have been applied for a business model.
static java.lang.String	AXISTOTAL This action defines that totaling is applied at the outermost hierarchy and level in the result set on either the column axis or the row axis.
static java.lang.String	EVENT_COALESCED_CHANGED This event is fired when the explicit join path has changed.
static java.lang.String	EVENT_EMPTY_DATA_FORMAT_CHANGED This event is fired when the empty data format has changed.
static java.lang.String	EVENT_FILTERS_CHANGED This event is fired when the list of filters has changed.
static java.lang.String	EVENT_QUERY_DEFINITION_CHANGED This event is fired when a change to an object has occurred that may cause query results to change from prior to the object change.
static java.lang.String	EVENT_QUERY_PROPERTY_CHANGED This event is fired when a query property has changed.
static java.lang.String	EVENT_REFERENCED_OBJECT_CHANGED This event is fired when any BusinessModelObject referenced by this BusinessQuery has changed.
static java.lang.String	EVENT_RESULT_ITEM_LIST_CHANGED This event is fired when the set of result items has changed.
static java.lang.String	EVENT_RESULT_ITEM_ROLE_CHANGED This event is fired when the role of a result item has changed.
static java.lang.String	EVENT_SOLVE_ORDER_CHANGED This event is currently never fired.
static java.lang.String	EVENT_SORT_CRITERIA_CHANGED This event is fired when the OLAP sort criteria has changed.
static java.lang.String	EVENT_SORT_DIRECTION_CHANGED This event is fired when the OLAP sort direction has changed.
static java.lang.String	EVENT_SORT_ORDER_CHANGED This event is fired when the sort order precedence list has changed.
static java.lang.String	EVENT_STEPS_CHANGED This event is fired when the step list has changed.
static java.lang.String	EVENT_SUPPORTED_ACTION_CHANGED This event is fired when the list of supported actions has changed.
static java.lang.String	EVENT_TOTAL_CHANGED This event is fired when totaling has been changed.
static java.lang.String	EVENT_TOTAL_LABEL_CHANGED This event is fired when a total label has been changed.
static java.lang.String	EVENT_TOTAL_LOCATION_CHANGED This event is fired when the explicit join path has changed.
static java.lang.String	EVENT_TOTAL_MODE_CHANGED This event is fired when totaling has been changed.
static java.lang.String	GRANDTOTAL This action defines if grand totaling is applied to outermost dimension for a business model.
static java.lang.String	SUBTOTAL This action defines if either all innermost rows or columns will be subtotaled for a business model.
static java.lang.String	TOTAL_NONE This action defines if neither rows or columns will be totaled for a business model.
static java.lang.String	WRITERESULT_MODEL_ELEMENT In the java.util.Map returned from the write(Element, Map) method, the value associated with this key is a org.w3c.dom.Element object giving the main element written for the query.
static java.lang.String	WRITERESULT_REFERENCED_INFOMAPS In the java.util.Map returned from the write(Element, Map) method, the value associated with this key is a java.util.List of BriefInformationMap objects which represent the information maps that were referenced in the XML that was written for the query.

Method Summary

void	addResultItem(DataItem dataItem, Role role) Adds a data item with the specified role to the set of data items contained in this business query that make up the requested results (called the result item list).
void	addResultItems(java.util.List dataItems, Role role) Adds a list of data items with the specified role to the set of data items contained in this business query that make up the requested results (called the result item list).
void	addStep(StepInterface step, Role stepRole) This method adds a Step to the ordered list of Steps that will be applied to a business query for a specific role.
BusinessModel	getBusinessModel() Returns the most extended business model object referenced by business items in this business query.
CascadeRuleSet	getCascadeRuleSet() Returns a CascadeRuleSet objects that describe the cascades needed if this business query were to be run at this time.
java.util.List<BusinessGroup>	getEffectiveGroups() Get effective groups for a business query.
java.util.List<BusinessGroup>	getEffectiveGroupsByType(BusinessGroup.Type type) Get a flattened list of the effective groups by type for the query.
java.util.List<BusinessGroup>	getEffectiveGroupsContaining(BusinessModelObject bi) Get the effective groups for the query that contain the specified business model object.
java.util.List<BusinessGroup>	getEffectiveGroupsContaining(BusinessModelObject bi, BusinessGroup.Type type) Get the effective groups by type for the query that contain the specified business model object.
java.lang.String	getEmptyDataFormat() Returns the replacement string to be used (in a result set generated from this query) for empty data.
com.sas.entities.EntityInterface	getEntity() Deprecated. Use getPromptValues;
java.util.List	getFilters() Returns the list of FilterItem objects last set on this object via setFilters()
StructureOfData	getInputStructure() Returns an indication as to the type or structure of the data used as input to this query.
BusinessQuery	getParentQuery() Returns the parent query for this BusinessQuery
com.sas.prompts.PromptValuesInterface	getPromptValues() Returns a prompt values object containing all of the prompts referenced by business items used in this BusinessQuery.
boolean	getQueryProperty(BusinessQueryProperty prop) Returns the value of a specified query property.
java.util.List<Reason>	getReasonsNotValid() Returns a list of reasons why this object is not a valid business query.
Role	getResultItemRole(DataItem dataItem) Returns the role for the given data item contained in the result item list.
java.util.List	getResultItems() Returns the list of data items contained in the result item list of this business query.
java.util.List	getResultItems(Role withThisRole) Returns the list of data items contained in the result item list of this business query that have been assigned the given role.
int	getResultSetIndex(java.lang.String dataItemID) Returns the column index in the resultset for the data item (contained in the result items list) with the given ID.
java.util.List	getSortCriteria(Role businessSortRole) This method gets the list of elements that are used to sort (order) on that was applied to this Business Query using the setSortCriteria method.
BusinessQueryActionType	getSortDirection(Role businessSortRole) This method gets the BusinessQueryActionType that describes the type of sorting that will be applied to this Business Query using the setSortDirection method.
java.util.List	getSortOrderPrecedence() This method gets the list of DataItems that was last set via setSortOrderPrecedence which specifies a precedence amongst a set of data items.
StepInterface	getStep(int stepNumber, Role stepRole) This method returns the Step (StepInterface) that has been applied for a specific role and step number. null can be returned if the object does not support steps, for example, XMLIntelligentQuery.
java.util.List<StepInterface>	getSteps(Role stepRole) This method returns an ordered list of steps (StepInterface) that will be applied to a business query for a specific role.
java.lang.String	getTotalLabel(Role businessTotalRole, java.lang.String typeOfTotal) This method gets the total label used for all totaling rows or columns in a businesss query.
BusinessQueryTotalLocationType	getTotalLocation() This method gets the location where total are inserted.
BusinessQueryTotalModeType	getTotalMode() This method gets the mode of totaling (either CUBE_VALUES or VISUAL_VALUES)
java.lang.String	getTotalType(Role businessTotalRole) This method gets the type of totaling that has been applied to a business query.
java.util.List	getValidActions() Returns a List of (BusinessQueryActionType) elements.
void	insertResultItemsAt(DataItem dataItem, Role role, int index) Inserts the specified a data item with the specified role to the set of data items contained in this business query that make up the requested results.
boolean	isActionSupported(BusinessQueryActionType actionType) Returns whether or not the specified BusinessQueryActionType is currenly supported by the BusinessQuery.
boolean	isValid() Returns whether this business query passes a set of base checks determining whether it is valid.
void	removeResultItem(DataItem dataItem) Removes the specified data item from the set of result items contained in this object.
void	removeResultItems(java.util.List dataItems) Removes a list of data items from the list of data items contained in this business query that make up the requested results (called the result item list).
void	removeStep(int stepNumber, Role stepRole) This method removes a Step to the ordered list of Steps that will be applied to a business query for a specific role.
void	setActionSupported(BusinessQueryActionType actionType, boolean actionSupported) Sets whether or not the specified BusinessQueryActionType is supported for this BusinessQuery.
void	setEmptyDataFormat(java.lang.String replacementString) This method specifies the replacement string to be used (in a result set generated from this query) for empty data.
void	setFilters(java.util.List filters) Sets the List of FilterItem objects on this business query to limit the results when this query is run.
void	setGroups(java.util.List<BusinessGroup> group) Set effective groups for a business query.
void	setQueryProperty(BusinessQueryProperty prop, boolean value) Sets the value of the specified query property in this object.
void	setResultItemRole(DataItem dataItem, Role role) Sets the role for the given data item contained in the result item list.
void	setResultItems(java.util.List dataItems) Sets the list of data items to use in the result item list.
void	setSelectedItems(java.util.List newSelectedItems) Sets the list of selected items to be used as result items.
void	setSortCriteria(java.util.List sortCriteria, Role businessSortRole) This method sets a list that contains the elements that will be used to sort (order) on.
void	setSortDirection(BusinessQueryActionType sortDirection, Role businessSortRole) This method sets the BusinessQueryActionType that describes the type of sorting that will be applied to this BusinessQuery.
void	setSortOrderPrecedence(java.util.List sortOrderPrecedence) This method sets the Sort Order Precedence for this query to the set of given data items.
void	setSteps(java.util.List<StepInterface> steps, Role stepRole) This method sets an ordered list of Steps that will be applied to a business query for a specific role.
void	setTotalLabel(java.lang.String totalLabel, Role businessTotalRole, java.lang.String typeOfTotal) This method sets a total label for all totaling rows or columns in a businesss query.
void	setTotalLocation(BusinessQueryTotalLocationType totalLocation) This method sets the location where total values are inserted.
void	setTotalMode(BusinessQueryTotalModeType totalLocation) This method sets the mode which the total values are displayed.
void	setTotalType(java.lang.String totalingType, Role businessTotalRole) This method sets the type of totaling that will be included in the resulting set of members defined as in a row or a column.
org.w3c.dom.Element	write(org.w3c.dom.Element parentElement) Serializes this model as a sub-element to the given DOM element and returns the subelement representing this model.

Methods inherited from interface com.sas.iquery.metadata.PropertyChangeListenee

addListener, getListeners, removeListener

Field Detail

EVENT_RESULT_ITEM_ROLE_CHANGED

static final java.lang.String EVENT_RESULT_ITEM_ROLE_CHANGED

This event is fired when the role of a result item has changed.

See Also:

Constant Field Values

EVENT_RESULT_ITEM_LIST_CHANGED

static final java.lang.String EVENT_RESULT_ITEM_LIST_CHANGED

This event is fired when the set of result items has changed.

See Also:

Constant Field Values

EVENT_FILTERS_CHANGED

static final java.lang.String EVENT_FILTERS_CHANGED

This event is fired when the list of filters has changed.

See Also:

Constant Field Values

EVENT_SORT_ORDER_CHANGED

static final java.lang.String EVENT_SORT_ORDER_CHANGED

This event is fired when the sort order precedence list has changed.

See Also:

Constant Field Values

EVENT_TOTAL_CHANGED

static final java.lang.String EVENT_TOTAL_CHANGED

This event is fired when totaling has been changed.

See Also:

Constant Field Values

EVENT_TOTAL_MODE_CHANGED

static final java.lang.String EVENT_TOTAL_MODE_CHANGED

This event is fired when totaling has been changed.

See Also:

Constant Field Values

EVENT_TOTAL_LABEL_CHANGED

static final java.lang.String EVENT_TOTAL_LABEL_CHANGED

This event is fired when a total label has been changed.

See Also:

Constant Field Values

EVENT_SORT_DIRECTION_CHANGED

static final java.lang.String EVENT_SORT_DIRECTION_CHANGED

This event is fired when the OLAP sort direction has changed.

See Also:

Constant Field Values

EVENT_SORT_CRITERIA_CHANGED

static final java.lang.String EVENT_SORT_CRITERIA_CHANGED

This event is fired when the OLAP sort criteria has changed.

See Also:

Constant Field Values

EVENT_SOLVE_ORDER_CHANGED

static final java.lang.String EVENT_SOLVE_ORDER_CHANGED

This event is currently never fired. It may be in the future when solve order precedence is implemented.

See Also:

Constant Field Values

EVENT_STEPS_CHANGED

static final java.lang.String EVENT_STEPS_CHANGED

This event is fired when the step list has changed.

See Also:

Constant Field Values

EVENT_QUERY_PROPERTY_CHANGED

static final java.lang.String EVENT_QUERY_PROPERTY_CHANGED

This event is fired when a query property has changed.

See Also:

Constant Field Values

EVENT_SUPPORTED_ACTION_CHANGED

static final java.lang.String EVENT_SUPPORTED_ACTION_CHANGED

This event is fired when the list of supported actions has changed.

See Also:

Constant Field Values

EVENT_EMPTY_DATA_FORMAT_CHANGED

static final java.lang.String EVENT_EMPTY_DATA_FORMAT_CHANGED

This event is fired when the empty data format has changed.

See Also:

Constant Field Values

EVENT_REFERENCED_OBJECT_CHANGED

static final java.lang.String EVENT_REFERENCED_OBJECT_CHANGED

This event is fired when any BusinessModelObject referenced by this BusinessQuery has changed. This means that of the objects that have been set on the BusinessQuery interface, one of those objects' definitions has changed.

See Also:

Constant Field Values

EVENT_QUERY_DEFINITION_CHANGED

static final java.lang.String EVENT_QUERY_DEFINITION_CHANGED

This event is fired when a change to an object has occurred that may cause query results to change from prior to the object change. This event may be used to monitor whether a query's definition has changed since last producing a resultset from the query.

See Also:

Constant Field Values

EVENT_COALESCED_CHANGED

static final java.lang.String EVENT_COALESCED_CHANGED

This event is fired when the explicit join path has changed.

See Also:

Constant Field Values

EVENT_TOTAL_LOCATION_CHANGED

static final java.lang.String EVENT_TOTAL_LOCATION_CHANGED

This event is fired when the explicit join path has changed.

See Also:

Constant Field Values

ALLTOTAL

static final java.lang.String ALLTOTAL

This totaling action defines that both subtotals and axistotals have been applied for a business model.

See Also:

Constant Field Values

SUBTOTAL

static final java.lang.String SUBTOTAL

This action defines if either all innermost rows or columns will be subtotaled for a business model. A subtotal is the value for a parent that has been added to the output because the user has asked for subtotals. It can therefore be either a Visual Total or a Cube Value.

See Also:

Constant Field Values

TOTAL_NONE

static final java.lang.String TOTAL_NONE

This action defines if neither rows or columns will be totaled for a business model.

See Also:

Constant Field Values

GRANDTOTAL

static final java.lang.String GRANDTOTAL

This action defines if grand totaling is applied to outermost dimension for a business model. TODO: This can not be removed until the relational generation code is modified to use AXISTOTALS.

See Also:

Constant Field Values

AXISTOTAL

static final java.lang.String AXISTOTAL

This action defines that totaling is applied at the outermost hierarchy and level in the result set on either the column axis or the row axis. Column totals are displayed as the last/first row(s) on the row axis. Row totals are displayed as the last/first column(s) on the column axis. When a total is coalesced, there is a single row/column for total. If total is not coalesced, you will see the natural multidimensional presentation.

See Also:

Constant Field Values

WRITERESULT_MODEL_ELEMENT

static final java.lang.String WRITERESULT_MODEL_ELEMENT

In the java.util.Map returned from the write(Element, Map) method, the value associated with this key is a org.w3c.dom.Element object giving the main element written for the query.

See Also:

Constant Field Values

WRITERESULT_REFERENCED_INFOMAPS

static final java.lang.String WRITERESULT_REFERENCED_INFOMAPS

In the java.util.Map returned from the write(Element, Map) method, the value associated with this key is a java.util.List of BriefInformationMap objects which represent the information maps that were referenced in the XML that was written for the query.

See Also:

Constant Field Values

Method Detail

getParentQuery

BusinessQuery getParentQuery()

Returns the parent query for this BusinessQuery

Returns:

the parent query for this BusinessQuery or null if none exists

getFilters

java.util.List getFilters()

Returns the list of FilterItem objects last set on this object via setFilters()

Returns:

List of FilterItem objects.

See Also:

setFilters(java.util.List)

setFilters

void setFilters(java.util.List filters)
                throws MetadataException

Sets the List of FilterItem objects on this business query to limit the results when this query is run.

Property change events signaled:

• EVENT_FILTERS_CHANGED

Parameters:

filters - List of FilterItem objects to be set on this business query

Throws:

MetadataException - if the operation could not be performed

See Also:

getQueryProperty

boolean getQueryProperty(BusinessQueryProperty prop)

Returns the value of a specified query property.

When a business query is initially created, all properties are initialized to a "false" value.

Parameters:

prop - specifies the query property whose value is to be returned.

Returns:

The value of the query property

See Also:

setQueryProperty(BusinessQueryProperty, boolean)

setQueryProperty

void setQueryProperty(BusinessQueryProperty prop,
                      boolean value)
                      throws MetadataException

Sets the value of the specified query property in this object.

Property change events signaled:

• EVENT_QUERY_PROPERTY_CHANGED

Parameters:

prop - The query property whose value is to be changed.

value - The value to change the the query property to.

Throws:

MetadataException - if the operation could not be performed

getEmptyDataFormat

java.lang.String getEmptyDataFormat()

Returns the replacement string to be used (in a result set generated from this query) for empty data.

Clients can use this property value to replace the value returned in the result set when rendering a display of values. Clients should not expect IQ to replace the actual values in the returned result set with this replacement string. A SQL/JDBC result set will not allow returning string data for numeric or date values.

Returns:

the value of the replacement string to use when empty data is found

See Also:

setEmptyDataFormat(java.lang.String)

setEmptyDataFormat

void setEmptyDataFormat(java.lang.String replacementString)
                        throws MetadataException

This method specifies the replacement string to be used (in a result set generated from this query) for empty data.

Clients can use this property value to replace the value returned in the result set when rendering a display of values. Clients should not expect IQ to replace the actual values in the returned result set with this replacement string. A SQL/JDBC result set will not allow returning string data for numeric or date values.

Property change events signaled:

• EVENT_EMPTY_DATA_FORMAT_CHANGED

Parameters:

replacementString - The value used to represent empty data in a ResultSet.

Throws:

MetadataException

See Also:

getEmptyDataFormat()

getInputStructure

StructureOfData getInputStructure()

Returns an indication as to the type or structure of the data used as input to this query. The returned object gives information like whether the input data is OLAP, relational, both, etc. The returned object does not give any indication on the type of data in the resultset when this query is run.

Returns:

an object describing the type of data *referenced* when this query is run.

addResultItem

void addResultItem(DataItem dataItem,
                   Role role)
                   throws MetadataException

Adds a data item with the specified role to the set of data items contained in this business query that make up the requested results (called the result item list).

Property change events signaled:

• EVENT_RESULT_ITEM_LIST_CHANGED

Parameters:

dataItem - The data item to add to the result item list

role - The role that the data item plays in the business query. If this is null no role is associated with the result item and a default role will be determined when this business query is run.

Throws:

MetadataException - if the operation could not be performed

addResultItems

void addResultItems(java.util.List dataItems,
                    Role role)
                    throws MetadataException

Adds a list of data items with the specified role to the set of data items contained in this business query that make up the requested results (called the result item list).

Property change events signaled:

• EVENT_RESULT_ITEM_LIST_CHANGED

Parameters:

dataItems - a list of DataItem objects to add to the result item list

role - The role that the data items play in the business query. If this is null no role is associated with the specified data items and default roles will be determined when this business query is run.

Throws:

MetadataException - if the operation could not be performed

insertResultItemsAt

void insertResultItemsAt(DataItem dataItem,
                         Role role,
                         int index)
                         throws MetadataException

Inserts the specified a data item with the specified role to the set of data items contained in this business query that make up the requested results. Each data item in the list with an index greater or equal to the specified index is shifted upward to have an index one greater than the value it had previously. The index must be a value greater than or equal to 0. (If the index is equal to the current size of the list, the data item is append to the end of the list.)

Property change events signaled:

• EVENT_RESULT_ITEM_LIST_CHANGED

Parameters:

dataItem - The data item to add to the result item list

role - The role that the data item plays in the business query. If this is null no role is associated with the result item and a default role will be determined when this business query is run.

index - where to insert the data item.

Throws:

MetadataException - if the operation could not be performed

java.lang.IllegalArgumentException - if the data item is null or the index is less then zero

removeResultItem

void removeResultItem(DataItem dataItem)
                      throws MetadataException

Removes the specified data item from the set of result items contained in this object. If the data item is not a result item, no action is taken.

Property change events signaled:

• EVENT_RESULT_ITEM_LIST_CHANGED

Parameters:

dataItem - a data item object to remove from the result item list

Throws:

MetadataException - if the operation could not be performed

removeResultItems

void removeResultItems(java.util.List dataItems)
                       throws MetadataException

Removes a list of data items from the list of data items contained in this business query that make up the requested results (called the result item list). Any dataItems not contained in the result item list cause no action to be taken.

Property change events signaled:

• EVENT_RESULT_ITEM_LIST_CHANGED

Parameters:

dataItems - a list of DataItem objects to be removed from the result item list

Throws:

MetadataException - if the operation could not be performed

setSelectedItems

void setSelectedItems(java.util.List newSelectedItems)
                      throws MetadataException

Sets the list of selected items to be used as result items. Any previous items are removed from the list of selected items contained within this query. The order of items within a particular role is dictated by the order of the items in the List argument. For example, if the selected items s_1, s_2, and s_3 are in the list and s_1 and S_3 are the ones with Role == ROW, then the order of items on the row axis is {s_1, s_3}.

Property change events signaled:

• EVENT_RESULT_ITEM_LIST_CHANGED

Parameters:

newSelectedItems - a list of selected items to be used as result items

Throws:

MetadataException - if the operation could not be performed

setResultItems

void setResultItems(java.util.List dataItems)
                    throws MetadataException

Sets the list of data items to use in the result item list. Any previous items in that list are removed from the list of result items contained within this query. No roles are specified for the

Property change events signaled:

• EVENT_RESULT_ITEM_LIST_CHANGED

Parameters:

dataItems - a list of data items to set in the result item list

Throws:

MetadataException - if the operation could not be performed

getResultItems

java.util.List getResultItems()

Returns the list of data items contained in the result item list of this business query.

Returns:

a list of DataItem objects

getResultItems

java.util.List getResultItems(Role withThisRole)
                              throws MetadataException

Returns the list of data items contained in the result item list of this business query that have been assigned the given role.

Returns:

a list of DataItem objects

Throws:

MetadataException - if the operation could not be performed

getResultItemRole

Role getResultItemRole(DataItem dataItem)
                       throws MetadataException

Returns the role for the given data item contained in the result item list. If the data item is inherited from a parent query but not returned in this query then the role will be returned as HIDDEN.

Returns:

a Role for the given data item in this business query or null if no role was specified when the data item was added as a result item, in which case a default role for the result item is determined when this business query is run.

Throws:

MetadataException - if the given data item is not in the result item list

setResultItemRole

void setResultItemRole(DataItem dataItem,
                       Role role)
                       throws MetadataException

Sets the role for the given data item contained in the result item list.

Property change events signaled:

• EVENT_RESULT_ITEM_ROLE_CHANGED

Parameters:

dataItem - a Role for the given data item in this business query

Throws:

MetadataException - if the given data item is not in the result item list

addStep

void addStep(StepInterface step,
             Role stepRole)
             throws MetadataException

This method adds a Step to the ordered list of Steps that will be applied to a business query for a specific role.

Property change events signaled:

• EVENT_STEPS_CHANGED

Parameters:

step - The step to be added to the StepManager

stepRole - The role (either Column or Row) where step will be applied.

Throws:

MetadataException

getStep

StepInterface getStep(int stepNumber,
                      Role stepRole)

This method returns the Step (StepInterface) that has been applied for a specific role and step number. null can be returned if the object does not support steps, for example, XMLIntelligentQuery.

A CompoundStep can contain CompoundSteps or Steps, but cannot directly or indirectly contain itself.

Parameters:

stepNumber -

stepRole - the role (either Column or Row) where step will be applied

Returns:

the step that has been applied for this role. null is possible if this BusinessQuery object does not support steps, for example, XMLIntelligentQuery.

Throws:

java.lang.IllegalArgumentException - if there is no step for this stepNumber and stepRole

getSteps

java.util.List<StepInterface> getSteps(Role stepRole)

This method returns an ordered list of steps (StepInterface) that will be applied to a business query for a specific role.

A CompoundStep can contain CompoundSteps or Steps, but can't directly or indirectly contain itself.

Parameters:

stepRole - the role (either Column or Row) where the step will be applied.

Returns:

an ordered list of Steps. The list may be empty, but never null.

setSteps

void setSteps(java.util.List<StepInterface> steps,
              Role stepRole)
              throws MetadataException

This method sets an ordered list of Steps that will be applied to a business query for a specific role. A CompoundStep can contain CompoundSteps or Steps, but can't directly or indirectly contain itself.

Property change events signaled:

• EVENT_STEPS_CHANGED

Parameters:

steps - the list of steps

stepRole - The role (either Column or Row) where step will be applied.

Throws:

MetadataException

removeStep

void removeStep(int stepNumber,
                Role stepRole)
                throws MetadataException

This method removes a Step to the ordered list of Steps that will be applied to a business query for a specific role.

Property change events signaled:

• EVENT_STEPS_CHANGED

Parameters:

stepNumber -

stepRole -

Throws:

MetadataException

getValidActions

java.util.List getValidActions()

Returns a List of (BusinessQueryActionType) elements. This list contains all all the Action Types that could be valid for this BusinessQuery. This differs from the getActionsSupported method in that this list does not define the set of Action that are currently supported by the BusinessQuery, but rather the list of Actions that can optionally be turned on or off. If an Action does not appear in this list then the consumer does not have the option of controlling this Action.

Returns:

List (of type BusinessQueryActionType) of valid Action Types.

isActionSupported

boolean isActionSupported(BusinessQueryActionType actionType)

Returns whether or not the specified BusinessQueryActionType is currenly supported by the BusinessQuery. This method is used by consumers to determine whether an Action should be enabled.

Parameters:

actionType - The type of BusinessQuery Action that is being queried.

Returns:

A boolean indicating whether a particular Action is supported for this BusinessQuery.

setActionSupported

void setActionSupported(BusinessQueryActionType actionType,
                        boolean actionSupported)
                        throws MetadataException

Sets whether or not the specified BusinessQueryActionType is supported for this BusinessQuery. Typically any Action can be disabled, but only the Action returned from the getValidActionTypes method can be enabled.

Property change events signaled:

• EVENT_SUPPORTED_ACTION_CHANGED

Parameters:

actionType - The type of BusinessQuery Action to enable or disable

actionSupported - A boolean indicating whether to enable or disable the BusinessQuery Action

Throws:

MetadataException - when trying to set an action to be supported when not in the valid list of supported actions

getSortOrderPrecedence

java.util.List getSortOrderPrecedence()

This method gets the list of DataItems that was last set via setSortOrderPrecedence which specifies a precedence amongst a set of data items.

Returns:

the user set list of data items defining the sort order precedence

See Also:

setSortOrderPrecedence

void setSortOrderPrecedence(java.util.List sortOrderPrecedence)
                            throws MetadataException

This method sets the Sort Order Precedence for this query to the set of given data items.

Property change events signaled:

• EVENT_SORT_ORDER_CHANGED

Parameters:

sortOrderPrecedence - a list a DataItem objects providing sort precedence

Throws:

MetadataException - when the action is not supported

See Also:

getSortDirection

BusinessQueryActionType getSortDirection(Role businessSortRole)

This method gets the BusinessQueryActionType that describes the type of sorting that will be applied to this Business Query using the setSortDirection method. To define a successful sort, both a sort direction and a sort criteria must be specified.

Sort directions that can be retrieved are:

• SORT_HIERARCHICAL_DESCENDING - Hierarchized (DESC) order
• SORT_HIERARCHICAL_ASCENDING - Hierarchized (ASC) order
• SORT_DESCENDING - Nonhierarchized (BDESC) order
• SORT_ASCENDING - Nonhierarchized (BASC) order.
• SORT_NONE - No sorting (ordering) .

Note: This method is specifically used to perform ordering for OLAP. This method is not used for relational business model. If businessSortRole is null, COLUMN is assumed. If an invalid Role is presented to this method, an error will be displayed and an SORT_NONE is returned. The valid sortDirection arguments that can be returned are:

Property change events signaled:

• EVENT_SORT_DIRECTION_CHANGED

Parameters:

businessSortRole - Defines whether this sort applied to a row or column.

Returns:

the type of sorting that will be applied to this Business Query.

See Also:

setSortDirection(BusinessQueryActionType, Role), setSortCriteria(java.util.List, Role)

setSortDirection

void setSortDirection(BusinessQueryActionType sortDirection,
                      Role businessSortRole)
                      throws MetadataException

This method sets the BusinessQueryActionType that describes the type of sorting that will be applied to this BusinessQuery. Only BusinessQueryActionTypes that are categorized as SORT and returned by getValidActions can be used in this method.

Note: This method is specifically used to perform ordering for OLAP. This method is not used for relational business model. There is no validation that occurs on the items defined in the sort criteria list. "Order" will arranges members of a specified set, optionally preserving or breaking the hierarchy. There are two varieties of Order: hierarchized (ASC or DESC) and nonhierarchized (BASC or BDESC, where B stands for Break hierarchy). The hierarchized ordering first arranges members according to their position in the hierarchy. Then it orders each level. The nonhierarchized ordering arranges members in the set without regard to the hierarchy.

Valid sortDirection arguments are:

• SORT_HIERARCHICAL_DESCENDING - Applies hierarchized (DESC) order parameter.
• SORT_HIERARCHICAL_ASCENDING - Applies hierarchized (ASC) order parameter.
• SORT_DESCENDING - Applies nonhierarchized (BDESC) order parameter.
• SORT_ASCENDING - Applies nonhierarchized (BASC) order parameter.
• SORT_NONE - remove any sorting (ordering) parameter.

To define a successful sort, both a sort direction and a sort criteria must be specified.

Property change events signaled:

• EVENT_SORT_DIRECTION_CHANGED

Parameters:

sortDirection - the type of sorting that will be applied to this query.

businessSortRole - Defines whether this sort applied to a row or column. If businessSortRole is null, COLUMN is assumed.

Throws:

MetadataException - when the action is not supported

java.lang.IllegalArgumentException - when either a invalid sortDirection or invalid businessSortRole is applied.

See Also:

getSortDirection(Role), setSortCriteria(List, Role)

getTotalType

java.lang.String getTotalType(Role businessTotalRole)

This method gets the type of totaling that has been applied to a business query. The type of totaling that will be returned are:

• ALLTOTAL - applies subtotaling and grandtotaling to all dimensions, their members, and their levels for a Row or Column to an business model.
• SUBTOTAL - applies sub-totals to all innermost dimensions, their members, and their levels for a Row or Column to an business model.
• GRANDTOTAL - applies totals to outmost dimension, their members, and their levels for a Row or Column to an business model.
• AXISTOTAL - synonym for GRANDTOTAL.
• TOTAL_NONE - deactivates any totals that have been applied to a relational or OLAP business model.

Parameters:

businessTotalRole - define whether this totaling is being set for a row or a column. If businessTotalRole is null, COLUMN is assumed.

Returns:

totalingType the type of totaling that was applied to query.

setTotalType

void setTotalType(java.lang.String totalingType,
                  Role businessTotalRole)
                  throws MetadataException

This method sets the type of totaling that will be included in the resulting set of members defined as in a row or a column. This is performed using MDX function called "Aggregation". Aggregation returns a calculated value using the appropriate aggregate function, based on the aggregation type of the members being used. The Totals definition is defined as follows: Using the "Country" member of the "Geographic" dimension, a calculated member called [Geographic].[Total] is displayed first against the defined measures (in the order that they have been defined in the business model). Therefore, in the case of "Sales_Sum" , total is calculated by adding (with Sum). In the case of "Sales_Max" total is calculated by taking the maximum.

Note: Several other methods will be added to support totaling in the future such as setTotalStyle (set label and formatting of the total row or column) and setTotalAggregation set aggregation factor).

The type of totaling applied can be:

• ALLTOTAL - applies subtotaling and grandtotaling to all dimensions, their members, and their levels for a Row or Column to an OLAP business model.
• SUBTOTAL - applies sub-totals to all innermost dimensions, their members, and their levels for a Row or Column to an OLAP business model.
• GRANDTOTAL - applies sub-totals to outmost dimension, their members, and their levels for a Row or Column to an OLAP business model.
• TOTAL_NONE - deactivates any totals that have been applied to a relational or OLAP business model.

Property change events signaled:

• EVENT_TOTAL_CHANGED

Parameters:

totalingType - the type of totaling that will be applied to this query.

businessTotalRole - define whether this totaling is being set for a row or a column. If businessTotalRole is null, COLUMN is assumed.

Throws:

MetadataException - when the action is not supported

java.lang.IllegalArgumentException - when a businessTotalRole is applied.

getTotalLabel

java.lang.String getTotalLabel(Role businessTotalRole,
                               java.lang.String typeOfTotal)

This method gets the total label used for all totaling rows or columns in a businesss query.

Note: If businessTotalRole is null, COLUMN is assumed. If an invalid Role is presented to this method, an error will be displayed and an empty string will be returned.

Parameters:

businessTotalRole - define whether this totaling is being set for a row or a column. If businessTotalRole is null, COLUMN is assumed.

typeOfTotal - defines whether total label will be applied to subtotal or grandtotal label.

Returns:

label defines label that is be used.

getTotalLocation

BusinessQueryTotalLocationType getTotalLocation()

This method gets the location where total are inserted.

Returns:

location that was set.

getTotalMode

BusinessQueryTotalModeType getTotalMode()

This method gets the mode of totaling (either CUBE_VALUES or VISUAL_VALUES)

Returns:

total mode.

setTotalLocation

void setTotalLocation(BusinessQueryTotalLocationType totalLocation)

This method sets the location where total values are inserted.

• Row_bottom_Column_right - appears bottom of row axis or right of column axis in relationship to children.
• Row_top_Column_left - appears top of row axis or left of column axis in relationship to children.
• Parent_placeholder - appear where the parent has been placed in the selection list.

  This option only applicable with BUSINESS_QUERY_OLAP_SELECTED_PARENTS_ONLY set to true.

Property change events signaled:

• EVENT_TOTAL_LOCATION_CHANGED

Parameters:

location - that was set.

setTotalMode

void setTotalMode(BusinessQueryTotalModeType totalLocation)

This method sets the mode which the total values are displayed.

• CUBE_VALUES - displays subtotal, alltotal, and grandtotal based on the cube values.
• VISUAL_VALUES - displays subtotal, alltotal, and grandtotal based on the values being displayed.

Property change events signaled:

• EVENT_TOTAL_MODE_CHANGED

Parameters:

location - that was set.

setTotalLabel

void setTotalLabel(java.lang.String totalLabel,
                   Role businessTotalRole,
                   java.lang.String typeOfTotal)
                   throws MetadataException

This method sets a total label for all totaling rows or columns in a businesss query. If no total label has been set, the default label that will be used is the combination of the dataItem plus the constant of "Total". If a specific total label for a dataitem needs to be set, use the method called "DataItem.setTotalLabel(String totalLabel)" to set a total label for a specific dataitem.

Note: This method may be deprecated for another method that will apply a full style name string pair. This pair would apply items such as labeling and formating (color, font, etc.)

Property change events signaled:

• EVENT_TOTAL_LABEL_CHANGED

Parameters:

totalLabel - defines label that will be used.

businessTotalRole - define whether this totaling is being set for a row or a column. If businessTotalRole is null, COLUMN is assumed.

typeOfTotal - defines whether total label will be applied to subtotal or grandtotal label.

Throws:

java.lang.IllegalArgumentException - when a businessTotalRole is applied.

MetadataException

getSortCriteria

java.util.List getSortCriteria(Role businessSortRole)

This method gets the list of elements that are used to sort (order) on that was applied to this Business Query using the setSortCriteria method. This list can contain a specific measure or a specific member/level of a dimension.

Note: If businessSortRole is null, COLUMN is assumed. If an invalid Role is presented to this method, an error will be displayed and an empty list will be returned.

Note: This method is specifically used to perform ordering for OLAP. This method is not used for relational business model.

Parameters:

businessSortRole - Defines whether this sort applied to a row or column.

Returns:

sort criteria This return list could contain a list of two string arrays (first array would be measures and second array would be member - represent by the string value of the measure or the member). The parameter could also contain a list that contains items that are either string values that represent members and data item entries that represent measure dataitems.

See Also:

setSortCriteria(java.util.List, com.sas.iquery.metadata.business.Role)

setSortCriteria

void setSortCriteria(java.util.List sortCriteria,
                     Role businessSortRole)
                     throws MetadataException

This method sets a list that contains the elements that will be used to sort (order) on. This "criteria" list can contain a specific measure or a specific member/level of a dimension. "Order" will arranges members of a specified set, optionally preserving or breaking the hierarchy. This method specifies what items (measure or member) will be sorted (ordered). To define a successful sort, both a sort direction and a sort criteria must be specified.

Note: There is no validation that occurs on the items defined in the sort criteria list.

Note: This method is specifically used to perform ordering for OLAP. This method is not used for relational information maps.

Property change events signaled:

• EVENT_SORT_CRITERIA_CHANGED

Parameters:

sortCriteria - This parameter could contain a list of two string arrays (first array would be measures and second array would be member - represent by the string value of the measure or the member). The parameter could also contain a list that contains items that are either string values that represent members and data item entries that represent measure dataitems.

businessSortRole - Defines whether this sort applied to a row or column.

Throws:

MetadataException - when the action is not supported

java.lang.IllegalArgumentException - when an invalid businessSortRole is applied.

See Also:

getSortCriteria(com.sas.iquery.metadata.business.Role), getSortDirection(com.sas.iquery.metadata.business.Role)

isValid

boolean isValid()

Returns whether this business query passes a set of base checks determining whether it is valid. Essentially this returns true if getReasonsNotValid() returns an empty list. If this object is not valid, one can call getReasonsNotValid() to find out why.

Returns:

a boolean value indicating whether this object is valid

getReasonsNotValid

java.util.List<Reason> getReasonsNotValid()

Returns a list of reasons why this object is not a valid business query. If this object is a valid business query, an empty list is returned.

This method is a union of all validation testing done by this object ... so it tests for role assignment validation, and other basic validation required in order to be a valid query to run.

Returns:

a List of Reason objects indicating why this object is not a valid business query. The list may be empty, but never null.

write

org.w3c.dom.Element write(org.w3c.dom.Element parentElement)
                          throws MetadataException

Serializes this model as a sub-element to the given DOM element and returns the subelement representing this model.

Parameters:

parentElement - element under which a new element should be created which holds this model's XML form.

Returns:

the subelement representing this model

Throws:

MetadataException - if the write fails

java.lang.NullPointerException - if given a null element argument

getBusinessModel

BusinessModel getBusinessModel()

Returns the most extended business model object referenced by business items in this business query.

Returns:

a BusinessModel object or null if no business items are contained in this business query

getResultSetIndex

int getResultSetIndex(java.lang.String dataItemID)

Returns the column index in the resultset for the data item (contained in the result items list) with the given ID. This method can be helpful in matching up columns in result sets to the original data items provided.

Parameters:

dataItemID - ID of a DataItem contained in the result item list

Returns:

the index into the resultset for the data item (contained in the result items list) with the given ID or -1 if no data item with the specified ID could be found in the result items that should be returned in a result set.

getEntity

com.sas.entities.EntityInterface getEntity()

Deprecated. Use getPromptValues;

Returns a "rolled-up" entity containing all of the prompts referenced by the business items used in this BusinessQuery. The first call to this method returns a new entity object with the Prompt object's attribute descriptors. Subsequent calls to this method return the same entity object with a refreshed set of attribute descriptors matching those currently referenced by prompts in use at the time of the call.

Returns:

EntityInterface the entity containing the attribute descriptors for the prompts referenced by items used in this BusinessQuery.

getPromptValues

com.sas.prompts.PromptValuesInterface getPromptValues()

Returns a prompt values object containing all of the prompts referenced by business items used in this BusinessQuery.

Returns:

PromptValuesInterface

getCascadeRuleSet

CascadeRuleSet getCascadeRuleSet()
                                 throws MetadataException

Returns a CascadeRuleSet objects that describe the cascades needed if this business query were to be run at this time. This set is composed of the cascades that are needed by stored process and filters from the ancestral business queries that are inherited by this business query.

Returns:

CascadeRuleSet

Throws:

MetadataException

java.lang.UnsupportedOperationException

setGroups

void setGroups(java.util.List<BusinessGroup> group)
               throws MetadataException

Set effective groups for a business query.

Throws:

MetadataException

getEffectiveGroups

java.util.List<BusinessGroup> getEffectiveGroups()

Get effective groups for a business query.

Returns:

List of effective groups.

getEffectiveGroupsByType

java.util.List<BusinessGroup> getEffectiveGroupsByType(BusinessGroup.Type type)

Get a flattened list of the effective groups by type for the query.

Returns:

List of effective groups.

getEffectiveGroupsContaining

java.util.List<BusinessGroup> getEffectiveGroupsContaining(BusinessModelObject bi,
                                                           BusinessGroup.Type type)

Get the effective groups by type for the query that contain the specified business model object. This returns only the immediate parent groups and not any nesting above the parent group.

Returns:

List of effective groups containing the object and of the specified type.

getEffectiveGroupsContaining

java.util.List<BusinessGroup> getEffectiveGroupsContaining(BusinessModelObject bi)

Get the effective groups for the query that contain the specified business model object. This returns only the immediate parent groups and not any nesting above the parent group.

Returns:

List of effective groups containing the object.

*** This interface is subject to change. ***