com.f1j.data.query
Interface DataQuery

public interface DataQuery

extends DataSet, com.f1j.util.SharedIndexed

Interface to a data query. The DataQuery interface provides API that makes data queries independent from data sources. Separating data queries from data sources makes it possible to have multiple queries on a single source.

Method Summary

Alias	addAlias(java.lang.String name) This will create and add an Alias for this query.
CalculatedField	addCalculatedField(java.lang.String name) This will create a CalculatedField in this query.
Index	addIndex(java.lang.String name) Creates a named indexing object.
void	checkIndexName(java.lang.String name) Checks whether the specified name would be valid as a new Index name.
Alias	findAlias(java.lang.String name) Looks up the alias with the specified name.
CalculatedField	findCalculatedField(java.lang.String name) Looks up the field with the specified name in this query.
Index	findIndex(java.lang.String name) Looks up the index with the specified name.
Alias	getAlias(int index) Returns the alias at the specified index.
int	getAliasCount() Returns the number of aliases for this query.
CalculatedField	getCalculatedField(int index) Returns the calculated field at the specified index.
int	getCalculatedFieldCount() Returns the number of calculated fields in this query.
java.util.Iterator	getCalculatedFieldIterator() Returns an iterator of all the calculated fields in the query.
Handler	getDataHandler() Returns the current data handler.
int	getDataHandlerType() Returns the current data handler type associated with this data query.
DataRange[]	getDataRanges() Returns the DataRanges currently listening to this data query.
Source	getDataSource() Returns the DataSource for this query.
GrantExpression	getGrantExpression() Returns the GrantExpression being used to secure this query.
Group	getGroup() Returns the Group this query belongs to.
int[]	getGroupingColumns() Reuturns the grouping columns.
java.lang.String	getIntermediateXmlOption(java.lang.String option) Returns the value of an option set for intermediate XML generation.
java.util.Properties	getIntermediateXmlOptions() Returns a Properties object filled out with the current set of options for intermediate XML generation.
com.f1j.data.query.QueryMetaData	getMetaData(boolean bUseCache) Returns a QueryMetaData object that describes the fields and groupings in this query.
java.lang.String	getName() Returns the defined name representing this data query.
com.f1j.data.query.QueryMetaData	getRawMetaData(boolean bUseCache) Returns a QueryMetaData object that describes the fields and groupings in this query directly from the database.
int	getRefreshIndex() Returns the refresh index for this data query.
int[]	getSortingColumns() Deprecated.
int[]	getSortingTypes() Deprecated.
boolean	getViewTime() Returns view-time flag.
java.util.Iterator	indexes() Returns an iterator for the indexes in this query.
boolean	isListening(DataRange range) Returns whether the specified data range is listening to this data query.
boolean	isListening(java.lang.String name) Returns whether a data range with the specified name is listening to this data query.
boolean	isParameterRequired(java.lang.String paramName) Returns whether this query requires the specified report parameter.
boolean	isParameterUsed(java.lang.String paramName) Returns whether this query uses the specified report parameter.
void	removeAlias(java.lang.String name) Removes the alias with the specified name from this query.
void	removeCalculatedField(java.lang.String name) Removes the calculated field with the specified name from this query.
void	removeIndex(java.lang.String name) Removes the index with the specified name from this query.
CalculatedField	renameCalculatedField(java.lang.String oldName, java.lang.String newName) Renames a Calculated Field in this query.
void	setDataHandlerType(int dataType) Changes the type of data this data query will handle.
void	setGrantExpression(GrantExpression expression) Sets the GrantExpression that should be used to secure this query.
void	setGroupingColumns(int[] groupings) Sets the grouping columns to be used.
void	setIntermediateXmlOption(java.lang.String option, java.lang.String value) Sets an option that applies to intermediate XML generation.
void	setName(java.lang.String sourceName) Sets the defined name that represents this data query.
void	setRefreshIndex(int index) Sets the refresh index for this data query.
void	setViewTime(boolean forceRefreshAtViewTime) Sets view-time flag.

Method Detail

getDataHandlerType

public int getDataHandlerType()

Returns the current data handler type associated with this data query.

Returns:

an int indicating the type of the current data handler:

DataHandler Data Types

Type	Description
kJDBCResultSet	JDBC result set type.
kDelimitedText	Character-delimited text type.
kPositionalText	Positionally delimited text type.
kXML	XML data type
kInvalid	indicates that an invalid data type was used

See Also:

setDataHandlerType(int), Handler

getDataHandler

public Handler getDataHandler()

Returns the current data handler.

Returns:

a com.f1j.data.handler.Handler object.

See Also:

Source.setDataHandler(int)

getDataRanges

public DataRange[] getDataRanges()

Returns the DataRanges currently listening to this data query.

Returns:

an array of DataRange objects.

See Also:

isListening(com.f1j.data.DataRange)

getDataSource

public Source getDataSource()

Returns the DataSource for this query.

Returns:

a DataSource object.

See Also:

DataRangeCollection.setDataSource(com.f1j.data.DataRange, com.f1j.data.source.Source)

getGroup

public Group getGroup()

Returns the Group this query belongs to.

getGroupingColumns

public int[] getGroupingColumns()

Reuturns the grouping columns. The column numbers are 1-based, not 0-based.

Returns:

an integer array indicating the grouping columns. Returns null if grouping is not supported for the data query type or if no grouping has been set.

See Also:

setGroupingColumns(int[])

getIntermediateXmlOption

public java.lang.String getIntermediateXmlOption(java.lang.String option)

Returns the value of an option set for intermediate XML generation.

Returns:

a string indicating the value of the specified option. See tables and explanation at setIntermediateXmlOption. Returns null if the option doesn't exist. Returns an empty string ("") if the option value is empty.

See Also:

getIntermediateXmlOptions(), setIntermediateXmlOption(java.lang.String, java.lang.String)

getIntermediateXmlOptions

public java.util.Properties getIntermediateXmlOptions()

Returns a Properties object filled out with the current set of options for intermediate XML generation.

Returns:

a java.util.Properties object with XML options. See tables and explanation at setIntermediateXmlOption

See Also:

getIntermediateXmlOption(java.lang.String), setIntermediateXmlOption(java.lang.String, java.lang.String)

getMetaData

public com.f1j.data.query.QueryMetaData getMetaData(boolean bUseCache)
                                             throws java.lang.Exception

Returns a QueryMetaData object that describes the fields and groupings in this query.

Returns:

an object that contains the query metadata or null if MetaData is unsupported.

getRawMetaData

public com.f1j.data.query.QueryMetaData getRawMetaData(boolean bUseCache)
                                                throws java.lang.Exception

Returns a QueryMetaData object that describes the fields and groupings in this query directly from the database.

Returns:

an object that contains the query metadata or null if MetaData is unsupported.

getSortingColumns

public int[] getSortingColumns()

Deprecated.

Returns the grouping columns. The column numbers are 1-based, not 0-based.

Returns:

an integer array indicating the sorting columns. Returns null if sorting is not supported for the data query type or if no sorting has been set.

See Also:

getSortingTypes()

getSortingTypes

public int[] getSortingTypes()

Deprecated.

Returns the sorting types as an integer array. The type will be one of the following values: 0 = No sort 1 = Ascending 2 = Descending.

Returns:

an integer array indicating the sorting types for the columns sorted. Returns null if sorting is not supported for the data query type or if no sorting has been set.

See Also:

getSortingColumns()

getName

public java.lang.String getName()

Returns the defined name representing this data query.

Returns:

a string indicating the defined name.

Specified by:

getName in interface DataSet

See Also:

setName(java.lang.String)

getRefreshIndex

public int getRefreshIndex()

Returns the refresh index for this data query. The refresh index is the 0-based rank order of refresh items. Setting refresh order to -1 means no refresh order preference.

Returns:

an int indicating the data query's location in the refresh order.

See Also:

setRefreshIndex(int)

isListening

public boolean isListening(DataRange range)

Returns whether the specified data range is listening to this data query.

Parameters:

range - the default or defined name of the data range.

Returns:

boolean true/false. true = specified data range is listening.

See Also:

getDataRanges()

isListening

public boolean isListening(java.lang.String name)

Returns whether a data range with the specified name is listening to this data query.

Parameters:

name - the default or defined name of the data range.

Returns:

boolean true/false. true = specified data range is listening.

See Also:

getDataRanges()

isParameterUsed

public boolean isParameterUsed(java.lang.String paramName)

Returns whether this query uses the specified report parameter.

Returns:

boolean true = collection uses the specified parameter.

isParameterRequired

public boolean isParameterRequired(java.lang.String paramName)

Returns whether this query requires the specified report parameter.

Returns:

boolean true = collection requires the specified parameter.

setGroupingColumns

public void setGroupingColumns(int[] groupings)
                        throws F1Exception

Sets the grouping columns to be used. The column numbers are 1-based, not 0-based.

Parameters:

groupings - an integer array indicating the grouping columns. if the array is null or empty, there is no grouping.

Throws:

F1Exception - Throws an UNSUPPORTED_FEATURE exception if the specified grouping is not supported for a specific data query type, or throws a BAD_ARGUMENT exception if any specified column number is less than 1

See Also:

getGroupingColumns()

setDataHandlerType

public void setDataHandlerType(int dataType)
                        throws F1Exception

Changes the type of data this data query will handle.

Parameters:

dataType - an int indicating a supported data type:

DataHandler Data Types

Type	Description
kJDBCResultSet	JDBC result set type.
kDelimitedText	Character-delimited text type.
kPositionalText	Positionally delimited text type.
kXML	XML data type
kInvalid	indicates that an invalid data type was used

Throws:

F1Exception - if an error occurs

See Also:

Handler, getDataHandler()

setIntermediateXmlOption

public void setIntermediateXmlOption(java.lang.String option,
                                     java.lang.String value)
                              throws F1Exception

Sets an option that applies to intermediate XML generation.

Parameters:

option - a string representing one of two possible XML generation options based on the XML schema version:

"900"	the "old" schema from an earlier release.
"901"	the "new" schema from a more current release.

value - One of the following strings indicating how to process column labels and table names in XML data and whether to enable data grouping:

XML Option Values (901 only)

Value	Set to	Description
IncludeColumnLabel	"true" or "false"	Include column labels (if present) from data source in XML.
IncludeTableName	"true" or "false"	Include table names (if present) from data source in XML.
EnableGrouping	"true" or "false"	Allow data grouping.
TrimStringValues	"true" or "false"	Trims leading and trailing whitespace from string values.

Note: These options only apply if the option parameter (SchemaVersion) is set to "901"

Example Syntax: The following are all of the current possible, valid method invocations.

               setIntermediateXmlOption("SchemaVersion", com.f1j.data.Constants.INTR_XML_SCHEMA_VERSION_900);
               setIntermediateXmlOption("SchemaVersion", com.f1j.data.Constants.INTR_XML_SCHEMA_VERSION_901);
               

The following three options are only valid if the "SchemaVersion" option is set to INTR_XML_SCHEMA_VERSION_901.

               setIntermediateXmlOption("IncludeTableName", "true");
               setIntermediateXmlOption("IncludeTableName", "false");
               

               setIntermediateXmlOption("IncludeColumnLabel", "true");
               setIntermediateXmlOption("IncludeColumnLabel", "false");
               

               setIntermediateXmlOption("EnableGrouping", "true");
               setIntermediateXmlOption("EnableGrouping", "false");
               

               setIntermediateXmlOption("TrimStringValues", "true");
               setIntermediateXmlOption("TrimStringValues", "false");
               

Throws:

F1Exception - BAD_ARGUMENT if an invalid option name or value is specified

See Also:

getIntermediateXmlOption(java.lang.String), getIntermediateXmlOptions()

setName

public void setName(java.lang.String sourceName)
             throws F1Exception

Sets the defined name that represents this data query.

Parameters:

sourceName - a defined name representing the data source.

Throws:

F1Exception - Returns a DUPLICATE_NAME error if sourceName is a name that already exists

See Also:

getName()

setRefreshIndex

public void setRefreshIndex(int index)

Sets the refresh index for this data query. The refresh index is the 0-based rank order of refresh items. Setting refresh order to -1 means no refresh order preference.

Parameters:

index - an int indicating the data query's location in the refresh order.

See Also:

getRefreshIndex()

addAlias

public Alias addAlias(java.lang.String name)
               throws com.f1j.util.InvalidNameException

This will create and add an Alias for this query.

Parameters:

name - The name of the alias.

Returns:

The alias that was created.

Throws:

com.f1j.util.InvalidNameException - when an alias or query exists with the specified name, or when the specified name is null, empty, or contains illegal characters.

Since:

12.0

See Also:

Alias

findAlias

public Alias findAlias(java.lang.String name)

Looks up the alias with the specified name. If no alias exists with this name, then null is returned.

Parameters:

name - The name of the alias to be found.

Returns:

The alias that matches the specified name.

Since:

12.0

See Also:

Alias

getAlias

public Alias getAlias(int index)

Returns the alias at the specified index.

Parameters:

index - The index of the desired alias.

Returns:

The alias at the specified index.

Throws:

java.lang.IndexOutOfBoundsException - when the index is invalid.

Since:

12.0

See Also:

Alias

getAliasCount

public int getAliasCount()

Returns the number of aliases for this query.

Returns:

The number of aliases for this query.

Since:

12.0

See Also:

Alias

removeAlias

public void removeAlias(java.lang.String name)

Removes the alias with the specified name from this query.

Parameters:

name - The name of the alias to be removed.

Since:

12.0

See Also:

Alias

setGrantExpression

public void setGrantExpression(GrantExpression expression)

Sets the GrantExpression that should be used to secure this query. Setting to null, removes all security.

Parameters:

expression - The grant expression to be used to secure this query.

Since:

12.0

See Also:

GrantExpression

getGrantExpression

public GrantExpression getGrantExpression()

Returns the GrantExpression being used to secure this query. Returns null if this query has not been secured.

Returns:

the GrantExpression being used to secure this query.

Since:

12.0

See Also:

GrantExpression

checkIndexName

public void checkIndexName(java.lang.String name)
                    throws com.f1j.util.InvalidNameException

Checks whether the specified name would be valid as a new Index name.

Parameters:

name - The name to give a potential index.

Throws:

com.f1j.util.InvalidNameException - when an index exists with the specified name, or when the specified name is null, empty, or contains illegal characters.

Since:

12.0

See Also:

Index

addIndex

public Index addIndex(java.lang.String name)
               throws com.f1j.util.InvalidNameException

Creates a named indexing object.

Parameters:

name - The name to give this index.

Returns:

The Index that was created.

Throws:

com.f1j.util.InvalidNameException - when an index exists with the specified name, or when the specified name is null, empty, or contains illegal characters.

Since:

12.0

See Also:

Index

findIndex

public Index findIndex(java.lang.String name)

Looks up the index with the specified name. If no index exists with this name, then null is returned.

Parameters:

name - The name of the index to be found.

Returns:

The index that matches the specified name.

Since:

12.0

See Also:

Index

indexes

public java.util.Iterator indexes()

Returns an iterator for the indexes in this query.

Returns:

an iterator for the indexes in this query.

Since:

12.0

See Also:

Index

removeIndex

public void removeIndex(java.lang.String name)

Removes the index with the specified name from this query.

Parameters:

name - The name of the index to be removed.

Since:

12.0

See Also:

Index

setViewTime

public void setViewTime(boolean forceRefreshAtViewTime)

Sets view-time flag.

Parameters:

forceRefreshAtViewTime - true to force this data set to refresh at view-time, or false to allow the refresh manager to determine when to refresh

Since:

12.0

getViewTime

public boolean getViewTime()

Returns view-time flag.

Returns:

true to force this data set to refresh at view-time, or false to allow the refresh manager to determine when to refresh

Since:

12.0

addCalculatedField

public CalculatedField addCalculatedField(java.lang.String name)
                                   throws F1Exception

This will create a CalculatedField in this query.

Parameters:

name - The name of the field.

Returns:

The field that was created for the query.

Throws:

F1Exception - if the specified name is null, empty, or contains illegal characters, or if the query already contains a field with this name.

Since:

12.0.2

See Also:

CalculatedField

findCalculatedField

public CalculatedField findCalculatedField(java.lang.String name)

Looks up the field with the specified name in this query. If no calculated field exists with this name, then null is returned.

Parameters:

name - The name of the field to be found.

Returns:

The calculated field that matches the specified name.

Since:

12.0.1

See Also:

CalculatedField

getCalculatedField

public CalculatedField getCalculatedField(int index)

Returns the calculated field at the specified index.

Parameters:

index - The index of the desired field.

Returns:

The field at the specified index.

Throws:

java.lang.IndexOutOfBoundsException - when the index is out of bounds.

Since:

12.0.1

See Also:

CalculatedField

renameCalculatedField

public CalculatedField renameCalculatedField(java.lang.String oldName,
                                             java.lang.String newName)
                                      throws InvalidArgumentException

Renames a Calculated Field in this query.

Parameters:

oldName - Name of the existing CalculatedField.

newName - New Name of the CalculatedField.

Returns:

The CalculatedField being renamed.

Throws:

InvalidArgumentException - if the new name is null, empty, or contains illegal characters, if the query already contains a field with this new name, or there is not an existing field with the specified old name.

Since:

12.0.1

See Also:

CalculatedField

getCalculatedFieldCount

public int getCalculatedFieldCount()

Returns the number of calculated fields in this query.

Returns:

The number of calculated fields.

Since:

12.0.1

See Also:

CalculatedField

removeCalculatedField

public void removeCalculatedField(java.lang.String name)
                           throws F1Exception

Removes the calculated field with the specified name from this query.

Parameters:

name - The name of the calculated field to be removed.

Throws:

F1Exception - if there's a problem removing the calculated field

Since:

12.0.2

See Also:

CalculatedField

getCalculatedFieldIterator

public java.util.Iterator getCalculatedFieldIterator()

Returns an iterator of all the calculated fields in the query.

Returns:

Iterator of all the calculated fields in the query

Since:

12.0.1

See Also:

CalculatedField