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

com.sas.iquery.dataservices
Class IQDataServices

com.sas.iquery.dataservices.IQDataServices

public class IQDataServices

Specifies an object that provides access to SAS Query Services. Currently, only a getPossibleFilterValues service is provided. This model should evolve to include other services consumers need. The IQDataServicesInterface helps define an simple API for surfacing SAS Query Services. For an example of how to use getPossibleFilterValues,

See Also:

PossibleFilterValue

Field Summary

static int	FORMATTED Used in getPossibleFilterValues() to request only formatted data should be returned.
static int	FORMATTED_UNFORMATTED Used in getPossibleFilterValues() to request both formatted and unformatted data should be returned.
static int	REASONCODE_IDPROP_MUST_SAVE reason code returned when trying to evaluate identity-driven properties on a map that has not been saved.
static int	REASONCODE_VALIDATION_WARNING_NO_RESOURCES reason code returned when the verify throws an exception due to no resources being used.
static int	REASONCODE_VALIDATION_WARNING_TYPE_CAST reason code returned when the verify throws an warning exception due to the user assigning either a Date, Time, or Timestamp type to an expression in the expression editor.
static int	UNFORMATTED Used in getPossibleFilterValues() to request only unformatted data should be returned.

Constructor Summary

IQDataServices()

Method Summary

java.util.List	getAvailableLevels(DataItem dataItem, BusinessQuery businessQuery) Gets the levels that are available for a dataItem based on the business query passed in.
com.sas.iquery.intelligentquery.QueryConnectionInterface	getConnection() Allows consumers to get a QueryConnector that was previously set on IQDataServices.
java.util.List	getMembers(DataItem dataItem, int stepNumber) Gets the members for a specific step set on the data item.
java.util.List	getMembers(DataItem dataItem, com.sas.storage.olap.MetadataInterface metaI) Gets the members for a specific step set on the data item.
java.util.List	getMembers(DataItem dataItem, java.lang.String level, com.sas.storage.olap.MetadataInterface metaI, com.sas.storage.olap.TupleElementInterface[] tupleElements) Gets the values for a data item based on the level and the business model passed in.
java.util.List	getPossibleFilterValues(DataItem dataItem) Returns a list of possible values.
java.util.List	getPossibleFilterValues(DataItem dataItem, Governing governing) Returns a list of possible values.
java.util.List	getPossibleFilterValues(DataItem dataItem, Governing governing, boolean honorFilters) Returns a list of possible values.
java.util.List	getPossibleFilterValues(DataItem dataItem, Governing governing, boolean honorFilters, boolean ignoreFormattingForced, int dataToReturn) Returns a list of possible values.
void	setConnection(com.sas.iquery.intelligentquery.QueryConnectionInterface qc) Allows consumers or applications to set a QueryConnector if they have one and want IQDataServices to use it.
void	setService(IntelligentQueryMetadataServiceInterface iqService) Sets the service whenever a new IQDataServicesInterface is created by the factory.
void	verify(BusinessItem item) This convenience method can be used to verify business items for use in a query.
void	verify(BusinessModel businessModel, ExpressionInterface expression) This convenience method can be used to verify expressions that may be used in a query.

Field Detail

FORMATTED

public static final int FORMATTED

Used in getPossibleFilterValues() to request only formatted data should be returned.

See Also:

Constant Field Values

FORMATTED_UNFORMATTED

public static final int FORMATTED_UNFORMATTED

Used in getPossibleFilterValues() to request both formatted and unformatted data should be returned.

See Also:

Constant Field Values

REASONCODE_IDPROP_MUST_SAVE

public static final int REASONCODE_IDPROP_MUST_SAVE

reason code returned when trying to evaluate identity-driven properties on a map that has not been saved. Such maps are not yet fully associated with a metadata server and so we sometimes might not be able to provide values for identity-driven properties on an unsaved map. In most cases however, we should be OK since the user already has other connections to the metadata server.

See Also:

Constant Field Values

REASONCODE_VALIDATION_WARNING_NO_RESOURCES

public static final int REASONCODE_VALIDATION_WARNING_NO_RESOURCES

reason code returned when the verify throws an exception due to no resources being used. The verify was successful and the expression was valid but it might cause problems if used without other data sources.

See Also:

Constant Field Values

REASONCODE_VALIDATION_WARNING_TYPE_CAST

public static final int REASONCODE_VALIDATION_WARNING_TYPE_CAST

reason code returned when the verify throws an warning exception due to the user assigning either a Date, Time, or Timestamp type to an expression in the expression editor. The verify was successful and the expression was valid but it might cause problems if used with other non-SAS data sources.

See Also:

Constant Field Values

UNFORMATTED

public static final int UNFORMATTED

Used in getPossibleFilterValues() to request only unformatted data should be returned.

See Also:

Constant Field Values

Constructor Detail

IQDataServices

public IQDataServices()

Method Detail

getAvailableLevels

public java.util.List getAvailableLevels(DataItem dataItem,
                                         BusinessQuery businessQuery)
                                  throws DataServicesException

Gets the levels that are available for a dataItem based on the business query passed in. This is used to allow the client to display only those levels that can be seen for this dataIten applied to this business query. Consider the following:

• An IQ "TIME" DataItem instance based on an OLAP heirarchy that contain YEAR, QTR, and MONTH levels.
• The "TIME" DataItem is assigned to the HIDDEN role in a table or graph's underlying BusinessQuery.
• We can assume there are either no filter applied or a parent filter has been applied. Where the parent filter has elimintated an level or levels that may have been originally defined in the cube.

Expended outcome:

• Case 1: No parent filter applied
  • getAvailableLevel(dataItem=TIME, businessQuery=tableQuery);

    Available Levels in the cube - YEAR, QTR, MONTH

    Available Levels returned - YEAR, QTR, MONTH

• Parent Relative Time Filter := Range from [2001].[QTR4].[November] to [2002].[QTR1].[March].

  Available Levels in the cube - YEAR, QTR, MONTH

  Available Levels returned - MONTH

This method will find the associated and appropriate session connection to the OLAP based on the BusinessQuery being passed.

A clean or "unfiltered" connection to OLAP server is made if a Parent BusinessQuery is used to construct the MetadataInterface. If a Child BusinessModel or Child BusinessQuery is used used to construct the MetadataInterface, then a "filtered" connection to the OLAP server is made.

It is the responsility of the client to release any query connection that they create.

Parameters:

dataItem - data item (that is a non-measure expression) used in obtaining the desired set of level names.

businessQuery - the businessQuery that you want associated to this dataItem. If this is null, the default businessQuery associated to this dataItem is used.

Returns:

List list of level names that are available for this dataItem.

Throws:

DataServicesException

getConnection

public com.sas.iquery.intelligentquery.QueryConnectionInterface getConnection()

Allows consumers to get a QueryConnector that was previously set on IQDataServices. If no QueryConnector has been set null is returned. This is not a factory method for creating a QueryConnector.

getMembers

public java.util.List getMembers(DataItem dataItem,
                                 int stepNumber)
                          throws DataServicesException

Gets the members for a specific step set on the data item. Issues an MDX query for members of the OLAP expression for either the base step or current (most recent) step.

This method is only implemented for OLAP data. The implementation generates a query, and executes the query on an OLAP server. Currently, the implementation is SAS specific and will not work on other OLAP engines.

Member data is returned in a list of embedded TupleElement objects. These objects wrapper tuples so that consumers can retrieve tuple information, for example unique name, or label.

This method builds its own query and connection. If the consumer sets a QueryConnector, the RetrievalPolicy that is held by the QueryConnector will be used in making a connection to the server.

The OLAP server connection is ALWAYS based on a "parent filtered" conversation. This means that if any effective filters have been applied to the BusinessModel holding this dataItem will be honored.

Parameters:

dataItem - data item used in obtaining the desired set of members for a particular step.

stepNumber - Specifies the desired step, either BASE_STEP or CURRENT_STEP.

Returns:

List list of TupleElement objects, an in memory representation of the member tuples. The tuples represent a set of members for a specific step.

Throws:

DataServicesException

getMembers

public java.util.List getMembers(DataItem dataItem,
                                 com.sas.storage.olap.MetadataInterface metaI)
                          throws DataServicesException

Gets the members for a specific step set on the data item. Issues an MDX query for members of the OLAP expression for either the base step or current (most recent) step.

This method is only implemented for OLAP data. The implementation generates a query, and executes the query on an OLAP server. Currently, the implementation is SAS specific and will not work on other OLAP engines.

Member data is returned in a list of embedded TupleElement objects. These objects wrapper tuples so that consumers can retrieve tuple information, for example unique name, or label.

This method builds its own query and connection. If the consumer sets a QueryConnector, the RetrievalPolicy that is held by the QueryConnector will be used in making a connection to the server.

This method will find the associated and appropriate session connection to the OLAP based on the MetadataInterface being passed. This means that the client will construct the metadataInterface that containes a parent filter session or a clean session based on whether the client passes in a Parent BusinessQuery or a Child BusinessQuery.

A clean or "unfiltered" connection to OLAP server is made if a parent BusinessModel or Parent BusinessQuery is used to construct the MetadataInterface.

If a Child BusinessModel or Child BusinessQuery is used used to construct the MetadataInterface, then a "filtered" connection to the OLAP server is made.level - the string value of the level that you wish get values from. businessModel - Specifies the businessModel that you want associated to this dataItem. If this is null, the default businessModel associated to this dataItem is used. &

Parameters:

dataItem - what is used to get the members of.

metadataInterface - Specifies the metadatainterface that was constructed by the client using BusinessQueryOLAPUtil.getMetadata

Returns:

List list of com.sas.storage.olap.embedded.TupleElement objects, an in memory representation of the member tuples. The tuples represent a set of members for a specific step.

Throws:

DataServicesException

getMembers

public java.util.List getMembers(DataItem dataItem,
                                 java.lang.String level,
                                 com.sas.storage.olap.MetadataInterface metaI,
                                 com.sas.storage.olap.TupleElementInterface[] tupleElements)
                          throws DataServicesException

Gets the values for a data item based on the level and the business model passed in. This will be used specially determine the values of a hidden dataItem Consider the following:

• An IQ "TIME" DataItem instance based on an OLAP heirarchy that contain YEAR, QTR, and MONTH levels.
• The "TIME" DataItem is assigned to the HIDDEN role in a table or graph's underlying BusinessQuery.
• We can assume there are no filters and no navigation steps are present, unless a step or a parent filter has been applied to the dataItem or the businessQuery.

Expended outcome:

• Case 1: No filters; No navigation steps.
  • getMembers(dataItem=TIME, level="Year", metadataInterface based on a tableGraphQuery);

    [2000], [2001], [2002], [2003]

  • getMembers(dataItem=TIME, level="Month", metadataInterface based on a tableGraphQuery);

    [2000].[QTR1].[January], ... [2000].[QTR4].[December], [2001].[QTR1].[January], ... [2001].[QTR4].[December], [2002].[QTR1].[January], ... [2002].[QTR4].[December], [2003].[QTR1].[January], ... [2003].[QTR4].[December]

  • Case 2: Child Relative Time Filter := Range from [2001].[QTR4].[November] to [2002].[QTR1].[March]
  • getMembers(dataItem=TIME, level="YEAR", metadataInterface based on a tableGraphQuery);

    [2001], [2002]

  • getMembers(dataItem=TIME, level="QTR", metadataInterface based on a tableGraphQuery);

    [20001]. [QTR4], [2002]. [QTR1]

  • getMembers(dataItem=TIME, level="Month", metadataInterface based on a tableGraphQuery);

    [20001]. [QTR4].[November], [20001]. [QTR4].[December], [20002]. [QTR1].[January],[20002]. [QTR1].[February], [20002]. [QTR1].[March],

• Time Data Item is drilled to [2001].[QTR2]
  • getMembers(dataItem=TIME, level="Year", metadataInterface based on a tableGraphQuery);

    [2001]

  • getMembers(dataItem=TIME, level="QTR", metadataInterface based on a tableGraphQuery);

    [20001]. [QTR2]

• Parent Relative Time Filter := Range from [2001].[QTR4].[November] to [2002].[QTR1].[March].

  NOTE: This is the same as Case 2 but involving a parent filter instead of a child filter.

  • getMembers(dataItem=TIME, level="YEAR", metadataInterface based on a lookthroughthrough tableGraphQuery );

    {} (i.e. the empty set)

  • getMembers(dataItem=TIME, level="Month", businessQuery=tableGraphQuery);

    [20001]. [QTR4].[November], [20001]. [QTR4].[December], [20002]. [QTR1].[January], [20002]. [QTR1].[February], [20002]. [QTR1].[March],

In the above case, the code issues an MDX query for members of the OLAP expression for the current (most recent) step. Gets the hierarchical values for a data item based on the starting point of a specific level and the metadataInterface that is passed in.

This method is only implemented for OLAP data. The implementation generates a query, and executes the query on an OLAP server. Currently, the implementation is SAS specific and will not work on other OLAP engines.

Member data is returned in a list of embedded TupleElement objects. These objects wraps tuples so that consumers can retrieve tuple information, for example unique name, or label.

This method builds its own query and may build its connection. If the consumer sets a QueryConnector, the RetrievalPolicy that is held by the QueryConnector will be used in making a connection to the server.

This method will find the associated and appropriate session connection to the OLAP based on the BusinessQuery being passed.

A clean or "unfiltered" connection to OLAP server is made if a Parent BusinessQuery is used to construct the MetadataInterface.

If a Child BusinessQuery is used, then a "filtered" (based on a parent filter) connection to the OLAP server is made. If a Child BusinessModel or Child BusinessQuery is used used to construct the MetadataInterface, then a "filtered" connection to the OLAP server is made.level - the string value of the level that you wish get values from. businessModel - Specifies the businessModel that you want associated to this dataItem. If this is null, the default businessModel associated to this dataItem is used.

It is the responsibility of the client to release any query connections that they create such as the QueryConnector for this IQueryServices object.

Parameters:

dataItem - data item used in obtaining the desired set of members for a particular step.

level - the string value of the level that you wish get values from.

metadataInterface - Specifies the metadatainterface that was constructed by the client using BusinessQueryOLAPUtil.getMetadata(BusinessModel) for the displayed/selected OLAPTableViewer.

tupleElements - Specifies the "clicked cell" (crossing address of the selected cell) in the displayed/selected OLAPTableViewer. It is possbile to pass in a null for this parameter. If a null is passed in then all of the members (irregardless of the axis location that was selected).

Returns:

List list of TupleElement objects, an in memory representation of the member tuples.

Throws:

DataServicesException

getPossibleFilterValues

public java.util.List getPossibleFilterValues(DataItem dataItem)
                                       throws DataServicesException

Returns a list of possible values. The list contains objects with formatted, and unformatted value pairs. The formatted and unformatted data is obtained from either a static list or executing a query. The result set of the query is iterated through to build up the return list of objects containing formatted and unformatted values. This method returns at most 1,000 records when querying the server.

Currently, this method is only implemented for relational data. The value of getLookupType() on the DataItem will determine how the returning values are created. LookupList will use the static list of values contained in the LookupList object. LookupByDataItem will generate a query and execute the query on a data source. LookupByQuery is not supported in this release. LookupNotAllowed will return an empty list. Currently, the implementation is SAS specific and will not work on other SQL engines.

Missing or empty values will be returned using a PossibleFilterValue object where the unformatted value is equal to null. The formatted value will be equal to the current setting for missing values.

Parameters:

dataItem - - data used in obtaining a possible set of filter values

Returns:

List - list of PossibleFilterValue containing the formatted and unformatted values, a flag indicating JDBC type information for the unformatted value.

Throws:

DataServicesException

getPossibleFilterValues

public java.util.List getPossibleFilterValues(DataItem dataItem,
                                              Governing governing)
                                       throws DataServicesException

Returns a list of possible values. The list contains objects with formatted, and unformatted value pairs. The formatted and unformatted data is obtained from either a static list or executing a query. The result set of the query is iterated through to build up the return list of objects containing formatted and unformatted values. Consumers can specify the maximum number of records to be returned when querying the server.

Currently, this method is only implemented for relational data. The value of getLookupType() on the DataItem will determine how the returning values are created. LookupList will use the static list of values contained in the LookupList object. LookupByDataItem will generate a query and execute the query on a data source. LookupByQuery is not supported in this release. LookupNotAllowed will return an empty list. Currently, the implementation is SAS specific and will not work on other SQL engines.

Missing or empty values will be returned using a PossibleFilterValue object where the unformatted value is equal to null. The formatted value will be equal to the current setting for missing values.

Parameters:

dataItem - - data used in obtaining a possible set of filter values

governing - - object specifying the maximum number or records to be returned from the server. If the object is set with a value of -1, this indicates all records should be returned from the server. If a null value is passed in for this parameter, the query will be set to return at most 1,000 rows.

Returns:

List - list of PossibleFilterValue containing the formatted and unformatted values, a flag indicating JDBC type information for the unformatted value.

Throws:

DataServicesException

getPossibleFilterValues

public java.util.List getPossibleFilterValues(DataItem dataItem,
                                              Governing governing,
                                              boolean honorFilters)
                                       throws DataServicesException

Returns a list of possible values. The list contains objects with formatted, and unformatted value pairs. The formatted and unformatted data is obtained from either a static list or executing a query. The result set of the query is iterated through to build up the return list of objects containing formatted and unformatted values. Consumers can specify the maximum number of records to be returned when querying the server.

Currently, this method is only implemented for relational data. The value of getLookupType() on the DataItem will determine how the returning values are created. LookupList will use the static list of values contained in the LookupList object. LookupByDataItem will generate a query and execute the query on a data source. LookupByQuery is not supported in this release. LookupNotAllowed will return an empty list. Currently, the implementation is SAS specific and will not work on other SQL engines.

Missing or empty values will be returned using a PossibleFilterValue object where the unformatted value is equal to null. The formatted value will be equal to the current setting for missing values.

Parameters:

dataItem - - data used in obtaining a possible set of filter values

governing - - object specifying the maximum number or records to be returned from the server. If the object is set with a value of -1, this indicates all records should be returned from the server. If a null value is passed in for this parameter, the query will be set to return at most 1,000 rows.

honorFilters - - flag specifying how to create a query. If the lookup type is LookupByDataItem and this flag is set, then the query that is created will include the effective set of filters for the DataItem's DataSelection. If honorFilters is true and the specified dataItem is based on a BusinessQuery containing prompted filters, this method expects that the prompt values have been assigned and uses them during query execution.

Returns:

List - list of PossibleFilterValue containing the formatted and unformatted values, a flag indicating JDBC type information for the unformatted value.

Throws:

DataServicesException

getPossibleFilterValues

public java.util.List getPossibleFilterValues(DataItem dataItem,
                                              Governing governing,
                                              boolean honorFilters,
                                              boolean ignoreFormattingForced,
                                              int dataToReturn)
                                       throws DataServicesException

Returns a list of possible values. The list contains objects with formatted, and unformatted value pairs. The formatted and unformatted data is obtained from either a static list or executing a query. The result set of the query is iterated through to build up the return list of objects containing formatted and unformatted values. Consumers can specify the maximum number of records to be returned when querying the server.

Currently, this method is only implemented for relational data. The value of getLookupType() on the DataItem will determine how the returning values are created. LookupList will use the static list of values contained in the LookupList object. LookupByDataItem will generate a query and execute the query on a data source. LookupByQuery is not supported in this release. LookupNotAllowed will return an empty list. Currently, the implementation is SAS specific and will not work on other SQL engines.

Missing or empty values will be returned using a PossibleFilterValue object where the unformatted value is equal to null. The formatted value will be equal to the current setting for missing values.

Parameters:

dataItem - - data used in obtaining a possible set of filter values

governing - - object specifying the maximum number or records to be returned from the server. If the object is set with a value of -1, this indicates all records should be returned from the server. If a null value is passed in for this parameter, the query will be set to return at most 1,000 rows.

honorFilters - - flag specifying how to create a query. If the lookup type is LookupByDataItem and this flag is set, then the query that is created will include the effective set of filters for the DataItem's DataSelection. If honorFilters is true and the specified dataItem is based on a BusinessQuery containing prompted filters, this method expects that the prompt values have been assigned and uses them during query execution.

ignoreFormattingForced - True if the data items formattingForced should be ignored

dataToReturn - FORMATTED, UNFORMATTED, or FORMATTED_UNFORMATTED. If FORMATTED is used then only the formatted data is returned, but it is returned in both the formatted and unformatted values of the PossibleFilterValue. Similar for UNFORMATTED.

Returns:

List - list of PossibleFilterValue containing the formatted and unformatted values, a flag indicating JDBC type information for the unformatted value.

Throws:

DataServicesException

setConnection

public void setConnection(com.sas.iquery.intelligentquery.QueryConnectionInterface qc)

Allows consumers or applications to set a QueryConnector if they have one and want IQDataServices to use it. If the consumer does not have access to a QueryConnector, an internal one will be used in IQDataServices. The internal QueryConnector will have the property such that it only lives to perform the requested operation like running a query to get a list of filter values. The internal QueryConnector will not be surfaced to consumers. Consumers can pass null to this method to clear the QueryConnector that was previously set by a consumer. Using this method will help reduce the number of server connections consumed by an and improve performance.

Parameters:

qc - - an QueryConnectionInterface object

setService

public void setService(IntelligentQueryMetadataServiceInterface iqService)

Sets the service whenever a new IQDataServicesInterface is created by the factory.

Parameters:

iqService - - an IntelligentQueryMetadataServiceInterface object

verify

public void verify(BusinessItem item)
            throws DataServicesException

This convenience method can be used to verify business items for use in a query. The business item can be either a data item or filter. The business item can be based on relational or OLAP data.

The performance of this method will vary from item to item. The calling application should be written to handle potentially slow performance.

Parameters:

item - - the business item to be verified

Throws:

DataServicesException - if the item is not valid or an error occurred during verification.

verify

public void verify(BusinessModel businessModel,
                   ExpressionInterface expression)
            throws DataServicesException

This convenience method can be used to verify expressions that may be used in a query.

The performance of this method will vary from expression to expression. The calling application should be written to handle potentially slow performance.

Parameters:

businessModel - - the business model to query against

expression - - the expression to be verified

Throws:

DataServicesException - if the item is not valid or an error occurred during verification.

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