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

com.sas.iquery.metadata.business
Interface DataItem

All Superinterfaces:

com.sas.iquery.metadata.business.AssociationItem, Base, BusinessItem, BusinessModelObject, BusinessModelResource, BusinessModelResourceReferencer, java.lang.Cloneable, DataItemContainerExpression, java.util.EventListener, ExpressionInterface, com.sas.iquery.metadata.business.ExtendedAttributes, LocalizableModelObject, LocalizableNamedObjectInterface, com.sas.util.LocalizableToStringInterface, ModelItem, ModelItemWithIdentity, NamedObjectInterface, PropertyChangeListenee, java.beans.PropertyChangeListener, UsabilityInterface

All Known Subinterfaces:

DataItemReference

public interface DataItem
extends DataItemContainerExpression, BusinessItem, ModelItemWithIdentity, LocalizableModelObject, com.sas.iquery.metadata.business.AssociationItem

Provides support for the mapping of physical data to a single unit of business data. It adds the ability to add things like formatting and ordering to the mapped business data. It provides the ability to leverage expressions in calculated data items. A data item represents the smallest unit of metadata set on a business query for which data is to be returned when a query is run.

Expression: a data item's core definition

DataItem objects have a core definition and a set of attributes that complement or add to that core definition to complete the data item's definition. The data item's expression is its core definition. A data item's expression can be based on other data items or on physical resources. Any resources used directly or indirectly in a data item's expression, must be based upon data sources defined in the data item's business model chain. For example, if a Column is used in a data item's expression, the column's table must be used in a DataSourceTable definition somewhere in the data item's business model chain. If an expression of Measures is used in a data item's expression, the Cube that those measures are from must be in a DataSourceCube definition somewhere in the data item's business model chain.

One can get the list of available functions and operators to be used in composing an expression for use on DataItem or FilterItem objects by using a ServerProperties object. The server properties can be obtained from the business model the data item is contained in. The specific set of functions, operators, etc. that are available from the server properties is based on the type of server being used to access the data source(s) defined in the business model chain.

Actions

Currently, both relational and OLAP data items directly use this class ... there is no subtypes for those types of data items. When necessary, one can tell which type of data item one has by calling getStructure().

Because the DataItem class is used for all relational and OLAP types of data items which do not have all the same types of capabilities/functionality, a set of "actions" (the class DataItemActionType) are defined which a data item can perform. Each type of action is associated with a setter/mutating method on the DataItem class.

Whether one is allowed to perform an action (call the method) is mainly determined by the expression or the resources used by the expression that has been set on the data item (for example, a ResourceAwareStringExpression based on a column, dimension, measure, etc.). When the setExpression method is called, it's set of supported actions is reset based upon its new expression. The list of supported actions for a data item can also be changed by denying the ability to perform an action via the setActionSupported() method. This prevents the data item and all DataItemReference objects built on the data item from performing that action.

Attributes

Metadata other than an expression are used on a data item to provide further functionality beyond the expression capabilities. For example,

• a relational data item's Label is used as the label for the column's label in output JDBC resultsets (see java.sql.ResultSetMetaData.getColumnLabel(int)).
• a data item's format attribute is used by the server to format the data item when used as a result item
• a data item's sort direction is used when the data item is used in a query
• a data item's steps are used for providing further "step-wise" modeling, especially filtering, to the data item beyond the data item's expression

ResultSet IDs

A ResultSet ID is an ID that one can set on a data item and when the data item is used as a non-hidden result item in a business query, the resultset ID for that data item is available indirectly from the resultset.

Currently resultset IDs are only returned for relational JDBC resultsets via the java.sql.ResultSetMetaData.getColumnName() method. They are currently not returned for OLAP resultsets.

ResultSet IDs are different from the ID that the base class BusinessModelObject provides. See the BusinessModelObject interface for information on uniquely identifying a data item or any other object that extends BusinessModelObject.

Data type ... no that's expression type

Java's relational database API defines numerous SQL or JDBC types in the java.sql.Types class. Those types are more granular than what is required by SAS Query Services. For example, in the Types class there are numerous types of character-oriented types: CHAR, CLOB, VARCHAR, LONGVARCHAR. There are numerous types of numeric-oriented types: BIGINT, DECIMAL, DOUBLE, FLOAT, INTEGER, etc. SAS Query Services defines types at a more coarse level (NUMERIC, CHARACTER, TIME, DATE, etc.) in the com.sas.iquery.metadata.expr.ExpressionTypes class.

In a nutshell, a data item's expression type (or object having an expression type) governs how it can be used within an expression.

Functions and Operators available from the ServerProperties object that are useful in creating arbitrarily complex expressions, are defined to have an allowed set of function signatures based on certain parameter types and returning a certain type. These types are based on SAS Query Services' expression types -- the coarse described types above. So, for example, the function MEAN is defined to have 4 signatures: each one having one parameter of one of the following types: NUMERIC, DATE, TIME, and TIMESTAMP. Because SAS Query Services uses more coarse expression types there are fewer defined allowable signatures for the functions and operators given by the server properties. One can get their hands on a ServerProperties object by using the BusinessModel.getServerProperties() method. One can also get their hands on a specific function by using the ServerProperties.getFunctionByNameID() method.

A data item's structure vs. its expression type

As mentioned above, a data item's expression type governs how the data item can be used within an expression and is typically numeric, character, date, time or a timestamp. An expression type does not describe what the structure of the data is that is used to make up that expression. For that we have a class StructureOfDataItem which contains several constants that are returned by DataItem.getStructure for describing the kind of data used to make up the data item's expression (for example, a relational column, an OLAP dimension, an OLAP measure, etc.)

DataItem vs. DataItemReference

There are two main types of data items -- custom data items (ones that are created by the BusinessModel.newDataItem() method) and data item references (created by the BusinessModel.newDataItemReference() method). Custom data items implement the DataItem interface but not the DataItemReference interface. But because the DataItemReference also extends DataItem, data item references are data items -- just not custom data items.

If you want to create a data item based on a previously defined data item to use with different attributes (format, etc.) one should create a data item reference based on the previously defined data item. If you want to create a brand new data item based on a new expression that you are creating, you should create a custom data item.

It is important to note that the getter methods on the DataItem interface return the most overridden value for an attribute when called on a DataItemReference object. For example, suppose an information map has a custom data item SALARY with a format of BEST. set on it. Also suppose that a data selection is created based on that information map with a DataItemReference A' based on the data item A. If the format for A' has not been set, the format (BEST.) from A is returned by the getFormat() method when called on A'. If the format has been set on A' to BEST5., then the getFormat method will return BEST5..

Likewise, the individual attributes on a DataItemReference object are overridden by the setter methods provided on the DataItem interface. The testing and clearing of the override of the individual attributes are provided by the methods on the DataItemReference that are of the form: isXXXXXModified() and resetXXXXX().

Changes to a data item's personality

Custom data items and data item references (that is, all data items) based on relational data (that is, DataItem.getStructure() returns StructureOfDataItem.STRUCTURE_COLUMN) allow for setting certain attributes that cause the data item's "personality" to change -- or rather it's expression type and its abilitity to be used validly in certain scenarios.

For example, if a data item is created that has its expression defined to be a column from a table, without any other attributes set the data item's expression type is the column's expression type (e.g ExpressionTypes.CHARACTER if the column is the same). But setting the data item's aggregation type to a Function that returns the ExpressionType.NUMERIC and now the data item's expression type is numeric.

This changing of a data item's personality by setting its attributes can be tricky. For example, suppose you create a filter (FilterItem) that uses a data item (DI) in it's expression. Say it abstractly looks something like:

 DI = "TUESDAY"
 

Prior to creating the filter's expression, the data item was defined to be a column in a table describing the weekday -- a character expression type. If that data item's definition is changed to aggregate on the data item (say using the COUNT function return the number of occurences of the data item's value in each row) the data item becomes an aggregated numeric expression type and the filter expression is no longer valid (comparing numerics to characters).

The data item attributes when changed that may cause a change in a data item's personality and therefore potentially causing other filter and data item modeling based on the data item to become invalid are:

• the aggregation type (Function) -- by setting or changing it one can cause the data item to change (1) whether it is aggregated or not and (2) the expression type of the data item
• the format -- care must be taken to keep the format up-to-date when changing a data item's expression type so that CHARACTER formats are not used on NUMERIC data items & vice versa.

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	DEFAULT_MEMBER_LEVEL_NAME Constant for surfacing the level of the default member of a specific hierarchy.
static java.lang.String	EVENT_DATA_ITEM_AGGREGATION_TYPE_CHANGED Indication that the data item's aggregation type has changed.
static java.lang.String	EVENT_DATA_ITEM_AGGREGATION_TYPES_SUPPORTED_CHANGED Indication that the data item's aggregation type that are supported are changed.
static java.lang.String	EVENT_DATA_ITEM_EXPRESSION_CHANGED An event indicating that the DataItem's expression has been set.
static java.lang.String	EVENT_DATA_ITEM_EXTENDED_TYPE_CHANGED Indication that the data item's extended types have changed.
static java.lang.String	EVENT_DATA_ITEM_FORMAT_CHANGED Indication that the data item's format has changed.
static java.lang.String	EVENT_DATA_ITEM_GROUP_FORMATTING_CHANGED Indication that the data item's group formatting has changed.
static java.lang.String	EVENT_DATA_ITEM_MEMBER_PROPERTIES_CHANGED Indication that the data item's member properties are changed.
static java.lang.String	EVENT_DATA_ITEM_SORT_CRITERIA_CHANGED Indication that the data item's sort criteria has changed.
static java.lang.String	EVENT_DATA_ITEM_SORT_DIRECTION_CHANGED Indication that the data item's sort direction has changed.
static java.lang.String	EVENT_DATA_ITEM_SORT_FORMATTING_CHANGED Indication that the data item's sort formatting has changed.
static java.lang.String	EVENT_DATA_ITEM_STARTING_LEVEL_CHANGED Indication that the data item's starting level are changed.
static java.lang.String	EVENT_DATA_ITEM_STARTING_LEVEL_NAME_CHANGED Indication that the data item's starting level are changed.
static java.lang.String	EVENT_DATA_ITEM_STEPS_CHANGED Indication that the data item's step definition have changed.
static java.lang.String	EVENT_DATA_ITEM_SUPPORTED_ACTIONS_CHANGED Indication that the data item's supported actions have changed.
static java.lang.String	EVENT_DATA_ITEM_USAGE_CHANGED Indication that the data item's usage has changed.
static java.lang.String	EVENT_DATA_LOOKUP_TYPE_CHANGED Indication that the data item's lookup type has changed.
static java.lang.String	EVENT_FORMATTING_FORCED_CHANGED Indication that the data item's forced formatting has been turned off or on.
static java.lang.String	EVENT_RESULT_SET_ID_CHANGED Indication that the data item's result set id has changed.

Fields inherited from interface com.sas.iquery.metadata.business.ModelItemWithIdentity

EVENT_DESCRIPTION_CHANGED, EVENT_HIDDEN_CHANGED, EVENT_ID_CHANGED, EVENT_LABEL_CHANGED

Fields inherited from interface com.sas.iquery.metadata.business.ModelItem

EVENT_OBJECT_PROPERTY_CHANGED

Fields inherited from interface com.sas.iquery.metadata.business.Base

EVENT_OBJECT_DEFINITION_CHANGED

Fields inherited from interface com.sas.iquery.metadata.business.LocalizableModelObject

EVENT_LOCALIZABLE_DESCRIPTIONS_CHANGED, EVENT_LOCALIZABLE_LABELS_CHANGED

Method Summary

void	addStep(StepInterface step) This method adds a Step to the ordered list of Steps.
Function	getAggregationType() Returns the aggregating function to use when aggregating on this DataItem This functions must come from the server properties for the InformationMap.
ExpressionInterface	getExpression() Returns the expression describing what the DataItem's value is composed of.
java.lang.String	getFormat() Returns the format that is used when formatting the data values for this data item.
DataItemActionType	getGroupFormatting() returns the formatting action type to use for grouping
Lookup	getLookupType() Returns the lookup type for this data item.
java.util.List	getMemberProperties() Returns the list of Member properties set on this DataItem.
java.util.List	getReasonsLabelNotValid(java.lang.String label) Determines if the specified label is usable.
java.lang.String	getResultSetID() Returns the ID that may be referred to in the resultset metadata for this data item.
java.util.List	getSortCriteria() This method will get a list that contains what elements will be used to sort on.
DataItemActionType	getSortDirection() This method returns the DataItemActionType that describes the type of sorting that will be applied to this DataItem.
DataItemActionType	getSortFormatting() returns the formatting action type to use for sorting
com.sas.iquery.metadata.physical.Level	getStartingLevel() Deprecated.
java.lang.String	getStartingLevelName() Returns the starting Level name that was set on this DataItem.
StepInterface	getStep(int stepNumber) This method returns an ordered list of Steps.
java.util.List	getSteps() This method returns an ordered list of Steps set on this object.
java.util.List	getSteps(boolean includeBaseDataItems) This method returns an ordered list of Steps for this data item and, if the input argument is true, any data items this data item is based upon.
StructureOfDataItem	getStructure() Returns an object giving the structure of this DataItem
java.util.List	getSupportedActionsList() Returns a List of supported actions for this DataItem.
java.util.List	getSupportedAggregationTypesList() Returns a List of supported aggregation Functions for this DataItem.
DataItemActionType	getUsage() Returns the default way this DataItem is to be used.
java.util.List	getValidActions() Returns a List of (DataItemActionType) elements.
java.util.List	getValidAggregationTypes() Returns the list of functions one can easily apply to this DataItem for aggregation purposes.
boolean	hasSteps() This method returns whether there is any steps to this dataItem.
boolean	isActionSupported(DataItemActionType actionType) Returns whether or not the specified DataItemActionType is currenly supported by the DataItem.
boolean	isAggregationTypeSupported(Function aggregationType) Returns whether a particular aggregationType is supported.
boolean	isCalculatedItem() This method indicates whether the DataItem can be described as a calculated item.
boolean	isValidFormat(java.lang.String format) This method indicates whether the specified format can be used with this data item.
void	removeStep(int stepNumber) This method removes a Step to the ordered list of Steps.
void	setActionSupported(DataItemActionType actionType, boolean actionSupported) Sets whether or not the specified DataItemActionType is supported for this DataItem.
void	setAggregationType(Function aggregationType) Sets the aggregation function to use when aggregating on this DataItem.
void	setAggregationTypeSupported(Function aggregationType, boolean aggregationTypeSupported) Sets whether a particular aggregation Function is supported.
void	setExpression(ExpressionInterface expression) Deprecated. use RootDataItem.setExpression(ExpressionInterface)
void	setFormat(java.lang.String format) Sets the type of Format to be used when formatting the data associated with this data item.
void	setGroupFormatting(DataItemActionType groupFormatting) sets the formatting action type to use for grouping
void	setLabel(java.lang.String label) Sets the label for this object.
void	setLookupType(Lookup lookupType) Set the lookup type for this data item.
void	setMemberProperties(java.util.List properties) Sets the list of Member properties on this DataItem.
void	setResultSetID(java.lang.String resultSetID) Sets the resultset ID for this data item.
void	setSortCriteria(java.util.List sortCriteria) This method will set a list that contains what elements will be used to sort on.
void	setSortDirection(DataItemActionType sortDirection) This method defines the DataItemActionType that describes the type of sorting that will be applied to this DataItem.
void	setSortFormatting(DataItemActionType sortFormatting) sets the formatting action type to use for sorting
void	setStartingLevel(com.sas.iquery.metadata.physical.Level level) Deprecated.
void	setStartingLevelName(java.lang.String levelName) Sets the starting Level name on this DataItem.
void	setSteps(java.util.List steps) This method sets an ordered list of Steps.
void	setUsage(DataItemActionType usage) Sets the way this DataItem is to be used.

Methods inherited from interface com.sas.iquery.metadata.expr.DataItemContainerExpression

containsUserTypedAggregation, getLeafDataItems

Methods inherited from interface com.sas.iquery.metadata.expr.ExpressionInterface

getExpressionType

Methods inherited from interface com.sas.iquery.metadata.business.BusinessModelObject

getBusinessModel, isContainedInBusinessModel, isIDOK, isReadOnly

Methods inherited from interface com.sas.iquery.metadata.business.ModelItemWithIdentity

getID, getIdentityString, getIntraModelID, isHidden, isUnresolved, setDescription, setIntraModelID, setIsHidden

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

addListener, getListeners, removeListener

Methods inherited from interface com.sas.iquery.metadata.business.UsabilityInterface

getReasonsUnusable, isUsableInQuery

Methods inherited from interface com.sas.iquery.metadata.business.BusinessModelResource

isUnresolved

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

getDescription, getLabel

Methods inherited from interface com.sas.iquery.metadata.business.BusinessModelResourceReferencer

getResources

Methods inherited from interface com.sas.iquery.metadata.business.LocalizableModelObject

getLocalizableProperties, getLocalizationPrependKey, setDescription, setDescriptions, setLabel, setLabels, setLocalizableProperties

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

getDescription, getDescriptions, getLabel, getLabels

Field Detail

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

EVENT_DATA_ITEM_SUPPORTED_ACTIONS_CHANGED

static final java.lang.String EVENT_DATA_ITEM_SUPPORTED_ACTIONS_CHANGED

Indication that the data item's supported actions have changed.

See Also:

Constant Field Values

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

EVENT_DATA_ITEM_AGGREGATION_TYPE_CHANGED

static final java.lang.String EVENT_DATA_ITEM_AGGREGATION_TYPE_CHANGED

Indication that the data item's aggregation type has changed.

See Also:

Constant Field Values

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

EVENT_DATA_ITEM_AGGREGATION_TYPES_SUPPORTED_CHANGED

static final java.lang.String EVENT_DATA_ITEM_AGGREGATION_TYPES_SUPPORTED_CHANGED

Indication that the data item's aggregation type that are supported are changed.

See Also:

Constant Field Values

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

EVENT_DATA_ITEM_EXTENDED_TYPE_CHANGED

static final java.lang.String EVENT_DATA_ITEM_EXTENDED_TYPE_CHANGED

Indication that the data item's extended types have changed.

See Also:

Constant Field Values

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

EVENT_DATA_ITEM_EXPRESSION_CHANGED

static final java.lang.String EVENT_DATA_ITEM_EXPRESSION_CHANGED

An event indicating that the DataItem's expression has been set. When this occurs all lists of valid & supported actions and aggregation types are reset to be the default for the given structure of the data item ... which the expression determines.

See Also:

Constant Field Values

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

EVENT_DATA_ITEM_FORMAT_CHANGED

static final java.lang.String EVENT_DATA_ITEM_FORMAT_CHANGED

Indication that the data item's format has changed.

See Also:

Constant Field Values

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

EVENT_DATA_ITEM_SORT_CRITERIA_CHANGED

static final java.lang.String EVENT_DATA_ITEM_SORT_CRITERIA_CHANGED

Indication that the data item's sort criteria has changed.

See Also:

Constant Field Values

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

EVENT_DATA_ITEM_SORT_DIRECTION_CHANGED

static final java.lang.String EVENT_DATA_ITEM_SORT_DIRECTION_CHANGED

Indication that the data item's sort direction has changed.

See Also:

Constant Field Values

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

EVENT_DATA_ITEM_SORT_FORMATTING_CHANGED

static final java.lang.String EVENT_DATA_ITEM_SORT_FORMATTING_CHANGED

Indication that the data item's sort formatting has changed.

See Also:

Constant Field Values

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

EVENT_DATA_ITEM_GROUP_FORMATTING_CHANGED

static final java.lang.String EVENT_DATA_ITEM_GROUP_FORMATTING_CHANGED

Indication that the data item's group formatting has changed.

See Also:

Constant Field Values

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

EVENT_DATA_ITEM_STEPS_CHANGED

static final java.lang.String EVENT_DATA_ITEM_STEPS_CHANGED

Indication that the data item's step definition have changed.

See Also:

Constant Field Values

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

EVENT_DATA_ITEM_USAGE_CHANGED

static final java.lang.String EVENT_DATA_ITEM_USAGE_CHANGED

Indication that the data item's usage has changed.

See Also:

Constant Field Values

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

EVENT_DATA_LOOKUP_TYPE_CHANGED

static final java.lang.String EVENT_DATA_LOOKUP_TYPE_CHANGED

Indication that the data item's lookup type has changed.

See Also:

Constant Field Values

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

EVENT_RESULT_SET_ID_CHANGED

static final java.lang.String EVENT_RESULT_SET_ID_CHANGED

Indication that the data item's result set id has changed.

See Also:

Constant Field Values

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

EVENT_FORMATTING_FORCED_CHANGED

static final java.lang.String EVENT_FORMATTING_FORCED_CHANGED

Indication that the data item's forced formatting has been turned off or on.

See Also:

Constant Field Values

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

EVENT_DATA_ITEM_MEMBER_PROPERTIES_CHANGED

static final java.lang.String EVENT_DATA_ITEM_MEMBER_PROPERTIES_CHANGED

Indication that the data item's member properties are changed.

See Also:

Constant Field Values

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

EVENT_DATA_ITEM_STARTING_LEVEL_CHANGED

static final java.lang.String EVENT_DATA_ITEM_STARTING_LEVEL_CHANGED

Indication that the data item's starting level are changed.

See Also:

Constant Field Values

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

EVENT_DATA_ITEM_STARTING_LEVEL_NAME_CHANGED

static final java.lang.String EVENT_DATA_ITEM_STARTING_LEVEL_NAME_CHANGED

Indication that the data item's starting level are changed.

See Also:

Constant Field Values

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

DEFAULT_MEMBER_LEVEL_NAME

static final java.lang.String DEFAULT_MEMBER_LEVEL_NAME

Constant for surfacing the level of the default member of a specific hierarchy. This can be passed into setStartingLevelName().

See Also:

Constant Field Values

Method Detail

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

getValidActions

java.util.List getValidActions()

Returns a List of (DataItemActionType) elements. This list contains all all the Action Types that could be valid for this DataItem. 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 DataItemActionType) of valid Action Types.

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

getSupportedActionsList

java.util.List getSupportedActionsList()

Returns a List of supported actions for this DataItem.

Returns:

a List of DataItemActionType objects

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

isActionSupported

boolean isActionSupported(DataItemActionType actionType)

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

Parameters:

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

Returns:

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

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

setActionSupported

void setActionSupported(DataItemActionType actionType,
                        boolean actionSupported)
                        throws MetadataException

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

Property change events signalled:

• EVENT_DATA_ITEM_SUPPORTED_ACTIONS_CHANGED

Parameters:

actionType - The type of DataItem Action to enable or disable

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

Throws:

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

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

getSortDirection

DataItemActionType getSortDirection()

This method returns the DataItemActionType that describes the type of sorting that will be applied to this DataItem. This method applies to both relational and OLAP data items.

Returns:

the type of sorting that will be applied to this DataItem.

See Also:

setSortDirection(com.sas.iquery.metadata.business.DataItemActionType)

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

setSortDirection

void setSortDirection(DataItemActionType sortDirection)
                      throws MetadataException

This method defines the DataItemActionType that describes the type of sorting that will be applied to this DataItem. Only DataItemActionTypes that are categorized as SORT and returned by getValidActions can be used in this method.

"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 sucessful sort, both a sort direction and a sort criteria must be specified.

Property change events signalled:

• EVENT_DATA_ITEM_SORT_DIRECTION_CHANGED

Parameters:

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

Throws:

MetadataException - when the action is not supported

See Also:

getSortDirection()

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

setSortCriteria

void setSortCriteria(java.util.List sortCriteria)
                     throws MetadataException

This method will set a list that contains what elements will be used to sort on. Note: This method is specifically used to perform ordering for OLAP. This method is not used for relational business model. "Order" will arrange 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 sucessful 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. This list can contain any member or measure.

Property change events signalled:

• EVENT_DATA_ITEM_SORT_CRITERIA_CHANGED

Parameters:

sortCriteria - List of string values that contain measure and members (defined as String[])

Throws:

MetadataException - when the action is not supported

See Also:

setSortDirection(com.sas.iquery.metadata.business.DataItemActionType)

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

getSortCriteria

java.util.List getSortCriteria()

This method will get a list that contains what elements will be used to sort on. This list would contain either one or two String[] objects where the first String[] object would always contain measures and the second String[] object would always contain members. This list could also be empty if sort is applied to only the dataitem.

Returns:

sort criteria List of string values that contain measure and members (defined as String[])

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

getUsage

DataItemActionType getUsage()

Returns the default way this DataItem is to be used. When a DataItem is initially created the default usage is set to USAGE_DETAIL.

Returns:

the default way this DataItem is to be used

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

setUsage

void setUsage(DataItemActionType usage)
              throws MetadataException

Sets the way this DataItem is to be used. Only DataItemActionTypes that are categorized as USAGE and returned by getValidActions can be used in this method.

Property change events signalled:

• EVENT_DATA_ITEM_USAGE_CHANGED

Parameters:

usage - the way this DataItem is to be used

Throws:

MetadataException - when the action is not supported

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

getAggregationType

Function getAggregationType()

Returns the aggregating function to use when aggregating on this DataItem This functions must come from the server properties for the InformationMap.

Returns:

a Function object giving the default aggregation function to use when aggregating on this DataItem or null if none specified

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

setAggregationType

void setAggregationType(Function aggregationType)
                        throws MetadataException

Sets the aggregation function to use when aggregating on this DataItem.

Property change events signalled:

• EVENT_DATA_ITEM_AGGREGATION_TYPE_CHANGED

Parameters:

aggregationType - a com.sas.iquery.metadata.serverprop.Function object giving the default aggregation function to use when aggregating on this DataItem or null if none

Throws:

MetadataException - when the aggregation type is not supported

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

getValidAggregationTypes

java.util.List getValidAggregationTypes()

Returns the list of functions one can easily apply to this DataItem for aggregation purposes. These functions must come from the server properties for the InformationMap.

Returns:

List of com.sas.iquery.metadata.serverprop.Function objects specifying which functions can easily be applied to this DataItem for aggregation purposes.

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

setMemberProperties

void setMemberProperties(java.util.List properties)
                         throws MetadataException

Sets the list of Member properties on this DataItem. The values of these member properties will be returned in the results of an OLAP query containing this data item. The DataItem's expression must be a Hierarchy, otherwise an exception will be thrown.

Property change events signalled:

• EVENT_DATA_ITEM_MEMBER_PROPERTIES_CHANGED

Parameters:

properties - a list of String property names

Throws:

MetadataException - when setting of Member properties is not supported on this DataItem.

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

getMemberProperties

java.util.List getMemberProperties()
                                   throws MetadataException

Returns the list of Member properties set on this DataItem.

Returns:

List of String property names that have been set on this DataItem

Throws:

MetadataException - if the list of member properties could not be determined.

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

setStartingLevel

void setStartingLevel(com.sas.iquery.metadata.physical.Level level)
                      throws MetadataException

Deprecated.

Sets the starting Level on this DataItem. The specified starting level will be used on its Hierarchy in a OLAP query when this data item is used. The DataItem's expression must be a Hierarchy, otherwise an exception will be thrown.

Property change events signalled:

• EVENT_DATA_ITEM_STARTING_LEVEL_CHANGED

Parameters:

level - the starting Level

Throws:

MetadataException - when setting of the starting Level is not supported on this DataItem.

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

setStartingLevelName

void setStartingLevelName(java.lang.String levelName)
                          throws MetadataException

Sets the starting Level name on this DataItem. The specified starting level name will be used on its Hierarchy in a OLAP query when this data item is used. The DataItem's expression must be a Hierarchy, otherwise an exception will be thrown.

Property change events signalled:

• EVENT_DATA_ITEM_STARTING_LEVEL_NAME_CHANGED

Parameters:

level - the starting Level

Throws:

MetadataException - when setting of the starting Level is not supported on this DataItem.

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

getStartingLevel

com.sas.iquery.metadata.physical.Level getStartingLevel()
                                                        throws MetadataException

Deprecated.

Returns the starting Level set on this DataItem.

Returns:

the starting Level may be null

Throws:

MetadataException - if the starting Level could not be determined.

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

getStartingLevelName

java.lang.String getStartingLevelName()
                                      throws MetadataException

Returns the starting Level name that was set on this DataItem.

Returns:

the starting Level name (may be null)

Throws:

MetadataException - if the starting Level could not be determined.

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

getSupportedAggregationTypesList

java.util.List getSupportedAggregationTypesList()

Returns a List of supported aggregation Functions for this DataItem.

Returns:

a List of Function objects

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

setAggregationTypeSupported

void setAggregationTypeSupported(Function aggregationType,
                                 boolean aggregationTypeSupported)
                                 throws MetadataException

Sets whether a particular aggregation Function is supported. Only the valid aggregation types can be supported, but support for any valid aggregation type can be removed.

Property change events signalled:

• EVENT_DATA_ITEM_AGGREGATION_TYPES_SUPPORTED_CHANGED

Parameters:

aggregationType - The type of aggregation Function to enable or disable.

Throws:

MetadataException

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

isAggregationTypeSupported

boolean isAggregationTypeSupported(Function aggregationType)

Returns whether a particular aggregationType is supported.

Parameters:

aggregationType - a boolean indicating whether a particular aggregationType is supported

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

addStep

void addStep(StepInterface step)
             throws MetadataException

This method adds a Step to the ordered list of Steps.

Property change events signalled:

• EVENT_DATA_ITEM_STEPS_CHANGED

Parameters:

step - The step to be added to the StepManager

Throws:

MetadataException - when a step is not supported.

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

getStep

StepInterface getStep(int stepNumber)

This method returns an ordered list of Steps. A CompoundStep can contain CompoundSteps or Steps, but can't directly or indirectly contain itself.

Returns:

An ordered list of Steps

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

hasSteps

boolean hasSteps()

This method returns whether there is any steps to this dataItem.

Returns:

steps are present in dataItem.

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

getSteps

java.util.List getSteps()

This method returns an ordered list of Steps set on this object. A CompoundStep can contain CompoundSteps or Steps, but can't directly or indirectly contain itself.

Returns:

An ordered list of Steps set on this object

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

getSteps

java.util.List getSteps(boolean includeBaseDataItems)

This method returns an ordered list of Steps for this data item and, if the input argument is true, any data items this data item is based upon. That is, if this DataItem is a DataItemReference it includes the steps of base DataItemReference objects in the chain until, and including, the base DataItem object.

Returns:

An ordered list of Steps. The steps are ordered starting with the "most base" data item. That is, if this is a DataItemReference, steps for the base data item are included in the list prior to steps for this data item.

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

setSteps

void setSteps(java.util.List steps)
              throws MetadataException

This method sets an ordered list of Steps. A CompoundStep can contain CompoundSteps or Steps, but can't directly or indirectly contain itself.

Property change events signalled:

• EVENT_DATA_ITEM_STEPS_CHANGED

Throws:

MetadataException - when a step is not supported.

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

removeStep

void removeStep(int stepNumber)

This method removes a Step to the ordered list of Steps.

Property change events signalled:

• EVENT_DATA_ITEM_STEPS_CHANGED

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

setExpression

void setExpression(ExpressionInterface expression)
                   throws MetadataException

Deprecated. use RootDataItem.setExpression(ExpressionInterface)

Sets the expression for the DataItem. The expression is the part of the DataItem that describes where its value is to come from. Examples of expression objects that can be set here are Column, Dimension, Hierarchy, Level, Measure, StringExpression, and FunctionCall.

Property change events signalled:

• EVENT_DATA_ITEM_EXPRESSION_CHANGED

Parameters:

expression - the part of the DataItem that describes where its value is to come from

Throws:

MetadataException - if an invalid object is set on the DataItem's expression

MetadataNotChangeableException - if this object is read-only

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

getExpression

ExpressionInterface getExpression()

Returns the expression describing what the DataItem's value is composed of.

Returns:

the part of the DataItem that describes where its value is to come from

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

getStructure

StructureOfDataItem getStructure()

Returns an object giving the structure of this DataItem

Returns:

the structure of the DataItem, which is represented by the StructureOfDataItem class.

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

getFormat

java.lang.String getFormat()

Returns the format that is used when formatting the data values for this data item.

Values of null and Strings consisting of 0 or more blanks are considered equivalent and if set as a format on a DataItem object causes the data item to have "no format" set on it.

For non-DataItemReference objects, this method returns what was last set by the setFormat() call on this object. For the more look-through oriented DataItemReference object, this method (like all look-through methods on DataItemReference) returns the most recently modified value (could be null or any of the values associated with "no format") looking from the object up its parentage chain of data items.

Returns:

the format that is used when formatting the data values for this data item

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

setFormat

void setFormat(java.lang.String format)
               throws MetadataException

Sets the type of Format to be used when formatting the data associated with this data item. The format value given is trimmed of any leading and trailing blanks as part of this method call.

Property change events signalled:

• EVENT_DATA_ITEM_FORMAT_CHANGED

Parameters:

format - the type of Format to be used when formatting the data

Throws:

MetadataNotChangeableException - if this object is read-only

MetadataException - if the DataItemActionType.OTHER_FORMAT is not supported.

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

isValidFormat

boolean isValidFormat(java.lang.String format)

This method indicates whether the specified format can be used with this data item.

Parameters:

format - the type of format to be used when formatting the data.

Returns:

A boolean indicating whether the specified format is valid with this data item. If the data item refers to an unresolved resource, this method always returns true.

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

setLookupType

void setLookupType(Lookup lookupType)
                   throws MetadataException

Set the lookup type for this data item. The lookup type determines how the possible filter values list is populated.

Property change events signalled:

• EVENT_DATA_LOOKUP_TYPE_CHANGED

Parameters:

lookupType - the part of the DataItem that describes how the possible filter values list is populated.

Throws:

java.lang.IllegalArgumentException - if the specified value is null. Use LookupNotAllowed to specify no lookup values.

MetadataException - if the DataItemActionType.OTHER_LOOKUP is not supported.

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

getLookupType

Lookup getLookupType()

Returns the lookup type for this data item.

Returns:

Lookup is the object that specifies the way possible filter values list is populated

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

isCalculatedItem

boolean isCalculatedItem()

This method indicates whether the DataItem can be described as a calculated item.

Returns:

True if the DataItem is a calculated item. Otherwise False.

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

getResultSetID

java.lang.String getResultSetID()

Returns the ID that may be referred to in the resultset metadata for this data item. For example, in JDBC result sets this ID is returned by the ResultSetMetaData.getColumnName() for the column returned for this data item when queries are run via SAS Query Services. Currently, this ID is only returned when JDBC resultsets are returned by SAS Query Services. OLAP resultsets do not have these IDs representing data items.

This ID is initially set to a unique value within the business model this object is created in. That means that if you use data items in a business query that are all from the same business model (for example, the data items are all data item references created within the same data selection) then the resultset IDs for all the data items used as result items will be unique. But if you use data items as result items from a mixture of business models (for example, by not creating data item references to those data items) then it is possible to create an invalid query because the default unique resultset ids are not unique across business models -- only within a business model.

See setResultSetID for uniqueness and characterset requirements for these IDs.

Returns:

the ID that may be referred to in the resultset metadata for this data item.

See Also:

setResultSetID(java.lang.String)

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

setResultSetID

void setResultSetID(java.lang.String resultSetID)
                    throws MetadataException

Sets the resultset ID for this data item. When a JDBC resultset is returned from SAS Query Services, this ID value is returned as a column's name in the resultset metadata. Resultset IDs are case-insensitive.

It is not possible to conclusively determine the allowed characterset for resultset IDs. Therefore, it is recommended that users stay within the confines of a small characterset for constructing resultset ids such as ("ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_") when possible. Invalid resultset ID values set on data items and used in data selections cause server errors when the data selection is run.

With that said, this method uses the following logic for doing basic validation of a resultset id. Resultset IDs can be any unicode character other than single or double quotes or ISO control or whitespace characters as defined by the Character.isISOControl() or Character.isWhitespace(). Resultset IDs must be case-insensitively unique within the set of result items used within a business query, otherwise the business query will be considered "not valid" and will not be runnable by SAS Query Services. Valid resultset IDs have a size between 1 and 32 characters in length.

Parameters:

resultSetID - the value to use as a resultset ID for this data item.

Throws:

java.lang.IllegalArgumentException - if an invalid argument is given.

MetadataException - if this operation could not be performed

See Also:

getResultSetID()

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

setLabel

void setLabel(java.lang.String label)
              throws MetadataException

Sets the label for this object. The server properties for the business model must be obtainable (non-null) in order for this method to succeed.

Property change events signalled:

• EVENT_LABEL_CHANGED

Specified by:

setLabel in interface ModelItemWithIdentity

Parameters:

label - the string to use as the label. Specifying null is allowed.

Throws:

MetadataNotChangeableException - if this BusinessModelObject is read-only

MetadataException - if the label is not valid or server properties not available

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

getReasonsLabelNotValid

java.util.List getReasonsLabelNotValid(java.lang.String label)
                                       throws MetadataException

Determines if the specified label is usable. Returns a list containing one or more reason objects if the label is invalid. Otherwise returns an empty list. Each reason object return contains the reason REASON_VALIDATE_RULE_FAILED with one of the following subreasons.

• SUBREASON_INVALID_LABEL_LENGTH
• SUBREASON_READ_ONLY_OBJECT
• SUBREASON_OBJECT_IS_UNRESOLVED
• SUBREASON_NOT_SPECIFIED

Parameters:

label - the data item label to be verified.

Returns:

A list of reason objects if the label is invalid.

Throws:

MetadataException - if the server properties for the specified data item is not defined.

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

setGroupFormatting

void setGroupFormatting(DataItemActionType groupFormatting)
                        throws MetadataException

sets the formatting action type to use for grouping

Parameters:

dataItem -

formattingActionType - (GROUP_BY_DEFAULT_BEHAVIOR, GROUP_BY_FORMATTED_VALUES, or GROUP_BY_UNFORMATTED_VALUES)

Throws:

MetadataException

java.lang.IllegalArgumentException

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

getGroupFormatting

DataItemActionType getGroupFormatting()
                                      throws MetadataException

returns the formatting action type to use for grouping

Parameters:

dataItem -

Returns:

GROUP_BY_DEFAULT_BEHAVIOR, GROUP_BY_FORMATTED_VALUES, or GROUP_BY_UNFORMATTED_VALUES.

Throws:

MetadataException

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

setSortFormatting

void setSortFormatting(DataItemActionType sortFormatting)
                       throws MetadataException

sets the formatting action type to use for sorting

Parameters:

dataItem -

formattingActionType - (SORT_BY_DEFAULT_BEHAVIOR, SORT_BY_FORMATTED_VALUES, or SORT_BY_UNFORMATTED_VALUES

Throws:

MetadataException

java.lang.IllegalArgumentException

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

getSortFormatting

DataItemActionType getSortFormatting()
                                     throws MetadataException

returns the formatting action type to use for sorting

Parameters:

dataItem -

Returns:

SORT_BY_DEFAULT_BEHAVIOR, SORT_BY_FORMATTED_VALUES, or SORT_BY_UNFORMATTED_VALUES.

Throws:

MetadataException

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