*** This class is subject to change. ***

com.sas.iquery.metadata.business
Class Role

com.sas.iquery.metadata.business.Role

All Implemented Interfaces:

com.sas.util.LocalizableToStringInterface

public class Role

Specifies the different multidimensional roles that a data item can take when it is used in the list of result items that is managed by the BusinessQuery interface.

Roles Definition by Data Source Type:

• Relational Roles

  The roles of data items have a special meaning when you are building relational queries: in order to return a plain table, all data items in a relational query must have a role of COLUMN. If any items in a relational query have a role of ROW, then the result will not be a regular tabular result set, but instead will be a multi-dimensional cross tabular data set, similar to those that are returned by OLAP queries.

  The role of HIDDEN will define several common uses:

  • Including other data items used to comprise the Join information used when constructing the query without returning those data item in the resultset.
  • It is possible to group by a data item that is not returned in the result set for a query set. You can do this by setting the "HIDDEN" role for the data item to be grouped by but not returned.

• OLAP roles

  Unlike relational queries, the type of result that is returned for OLAP queries is always multi-dimensional, even if all the items are to be set to be on the COLUMN role. Roles have multiple purposes for the OLAP data selection. A role can define an axis specification or a slicer specification.

  A role can also define whether a data item is included in the query or whether the data item is visible. If a role of HIDDEN is applied, the data item is not included in the query and it is not visible.

  An axis specification - This would mean that a dataItem was defined as a ROW or COLUMN. It defines the dataItem as units (members) along each output axis (defined as a vertical or horizonal axis)

  A slicer specification - a role of BACKGROUND defines what slice of the cube is to aggregated. Applying a slicer role would define a where clause. The WHERE clause further restricts the result set. The axis that is formed by the WHERE clause is referred to as the slicer. The WHERE clause determines which dimension or member is used as a slicer dimension. This restricts the extracting of data to a specific dimension or member. Any dimension that does not appear on the output axis (in the SELECT clause as either a ROW or COLUMN) can be named on the slicer.

  For example: To limit the result to Sales in 1997 and display only Unit Sales, these hierarchical levels are placed in the slicer specification.

Summary of Rules on How Roles are Applied to OLAP Data Items:

1. DataItems coming from same Dimension can't be assigned different roles unless the role that is being assigned is HIDDEN.
2. Except for Measures only one DataItem per Dimension is allowed - this could go away in the future (not MDX rule, but IQ rule)
3. DataItems with more than one Member must be modified if placed on the BACKGROUND Role.
4. Follow-up to the Rule 3, only 1 Measure can live on the BACKGROUND since measures is an exception case where multiple data items may be included.
5. Nulls are valid if they do not cause a conflict with Rules (2) and (4).
6. If the ROW Role is used, at least one result item must be assigned to COLUMN.
7. The PAGE Role are not supported in OLAP at this time.
*
• ROLAP Roles

  All data items must have a role of either COLUMN or a role of ROW, it will result in a multi-dimensional cross tabular data set, similar to those that are returned by OLAP queries.

  The Role of BACKGROUND will result in the item not being used as a result column, or included in the sort items or groupings.

  The Role of HIDDEN will result in the item not being used as a result column, but it will be included as a sort item and in the groupings. This can cause multiple rows to return with identical grouping category values.

Field Summary

static Role	BACKGROUND This role is used, when specifying a data item as a result item in a BusinessQuery, to request the result item to be on the BACKGROUND axis in the result set returned by SAS Query Services' data services component when processing the query.
static Role	COLUMN This role is used, when specifying a data item as a result item in a BusinessQuery, to request a result item to be on the COLUMN axis in the result set returned by SAS Query Services' data services component when processing the query.
static Role	HIDDEN This role is used, when specifying a data item as a result item in a BusinessQuery, to request the result item to be processed as if it were to be returned as a result item but to not return it in the resultset.
static Role	PAGE Deprecated. do not use
static Role	ROW This role is used, when specifying a data item as a result item in a BusinessQuery, to request a result item to be on the ROW axis in the result set returned by SAS Query Services' data services component when processing the query.

Method Summary

static boolean	isInactiveRole(BusinessQuery query, Role role) Checks the role specified for the query specified to see if that role when assigned to a result item will result in the result item being ignored.
static boolean	isOutputResultRole(BusinessQuery query, Role role) Returns true if the an item using this role will be displayed as an output result on an axis or in a cell.

Field Detail

*** This field is subject to change. ***

ROW

public static final Role ROW

This role is used, when specifying a data item as a result item in a BusinessQuery, to request a result item to be on the ROW axis in the result set returned by SAS Query Services' data services component when processing the query.

If assigning this role is not valid for a given data item in the context of how other data items and their roles are assigned in a query, the query will become invalid and a Reason object is available via the BusinessQuery.getReasonsNotValid() method.

*** This field is subject to change. ***

COLUMN

public static final Role COLUMN

This role is used, when specifying a data item as a result item in a BusinessQuery, to request a result item to be on the COLUMN axis in the result set returned by SAS Query Services' data services component when processing the query.

If assigning this role is not valid for a given data item in the context of how other data items and their roles are assigned in a query, the query will become invalid and a Reason object is available via the BusinessQuery.getReasonsNotValid() method.

*** This field is subject to change. ***

BACKGROUND

public static final Role BACKGROUND

This role is used, when specifying a data item as a result item in a BusinessQuery, to request the result item to be on the BACKGROUND axis in the result set returned by SAS Query Services' data services component when processing the query.

If assigning this role is not valid for a given data item in the context of how other data items and their roles are assigned in a query, the query will become invalid and a Reason object is available via the BusinessQuery.getReasonsNotValid() method.

*** This field is subject to change. ***

PAGE

public static final Role PAGE

Deprecated. do not use

This role is defined for future use (it is NOT currently supported). The role will be used when specifying a data item as a result item in a BusinessQuery, to signify a new Axis for the multidimensional result set. An example of Page role is a BY Group report where the Country has a page role and the other result items are information shown for each Country. The role is only valid when the structure of the data is OLAP.

If assigning this role is not valid for a given data item in the context of how other data items and their roles are assigned in a query, the query will become invalid and a Reason object is available via the BusinessQuery.getReasonsNotValid() method.

*** This field is subject to change. ***

HIDDEN

public static final Role HIDDEN

This role is used, when specifying a data item as a result item in a BusinessQuery, to request the result item to be processed as if it were to be returned as a result item but to not return it in the resultset.

Several common uses of this role are:

• Setting sort information on a data item and adding the data item with a hidden role in the result items to sort on that data item. Note that method of providing sort order precedence is not as general as using the BusinessQuery.setSortOrderPrecedence method.
• Including other data items used to comprise the Join information used when constructing the query without returning those data item in the resultset.

If assigning this role is not valid for a given data item in the context of how other data items and their roles are assigned in a query, the query will become invalid and a Reason object is available via the BusinessQuery.getReasonsNotValid() method.

Method Detail

*** This method is subject to change. ***

isInactiveRole

public static boolean isInactiveRole(BusinessQuery query,
                                     Role role)

Checks the role specified for the query specified to see if that role when assigned to a result item will result in the result item being ignored. (In Relational and ROLAP this item will still be used to calculate the join path used.)

Parameters:

query - BusinessQuery that is being examined.

role - Selected item's role.

Returns:

true if this Role will inactivate a result item (it may still be used to join tables together) and false otherwise.

*** This method is subject to change. ***

isOutputResultRole

public static boolean isOutputResultRole(BusinessQuery query,
                                         Role role)

Returns true if the an item using this role will be displayed as an output result on an axis or in a cell. HIDDEN and BACKGROUND will be treated appropriately for the type of selection being used for the query. HIDDEN in OLAP means not visible, BACKGROUND in Relational means not visible.

Parameters:

query -

role -

Returns:

true for roles that will appear in the results of the query

See Also:

isInactiveRole(BusinessQuery,Role)

*** This class is subject to change. ***