com.endeca.portal.data
Class DataSource

java.lang.Object
  com.endeca.portal.data.DataSource

public class DataSource
extends java.lang.Object

DataSource instances encapsulate a connection to an MDEX Engine, a current QueryState on the connection, handles the logic of executing a query on an MDEX to get results, and handles the logic of altering the QueryState.

See Also:

QueryState

Field Summary

static java.lang.String	RECORD_KIND_DATA
static java.lang.String	RECORD_KIND_PROPERTIES

Constructor Summary

DataSource(javax.portlet.PortletRequest request, java.lang.String dataSourceId)
Construct a DataSource instance referring to a particular data source.

Method Summary

void	clearCachedGlobalAttributeSettings() Only for use with Discovery Service enabled datasources Clears any session-cached Global UAM settings from the underlying MDEXState.
void	clearCachedMDEXAttributes() Clears any session-cached attributes from the underlying MDEXState.
void	clearEntityCaches() Clears any information that is cached related to the entity information for this data source.
com.endeca.mdex.conversation.Request	createDiscoveryServiceQuery(QueryState state) Create a Discovery Service Request instance from a query state, using the current request state.
void	createOrUpdateAttributeGroup(Group uamGroup) Only for use with Discovery Service enabled datasources
com.endeca.mdex.sconfig._2010.types.DeleteEntitiesResponse	deleteSemanticEntities(java.util.List<java.lang.String> entityKeys) Deletes all of the entity definitions in the MDEX with the passed keys.
QueryResults	execute() Executes a query representing the data source's QueryState.
QueryResults	execute(QueryState queryState) Executes a query representing the QueryState.
com.endeca.mdex.conversation.Results	execute(com.endeca.mdex.conversation.Request query) Applies security and executes query against the current request's State.
com.endeca.mdex.config.services.types.Results	executeConfigServiceUpdateOperation(com.endeca.mdex.config.services.types.ConfigTransaction transaction) Executes update config service transactions
java.lang.String	getDescription() get the DataSource's description
javax.xml.namespace.QName	getEventName() Retrieve the event name that gets fired/listened for when this data source changes.
AttributeSettings	getGlobalAttributeSettings() Gets the Global Unified Attribute Model for this datasource.
java.lang.String	getId() get the DataSource's ID
QueryState	getInitialQueryState() Retrieve the initial QueryState on this data source, which is the QueryState defined in the data source's initial JSON configuration
MDEXAttribute	getMDEXAttribute(java.lang.String key) Convenience method to retrieve an attribute of a data source
MDEXAttributeList	getMDEXAttributes() Retrieves a list of attributes available in the MDEX engine, by performing a key properties query and wrapping the results for convenience.
MDEXState.MDEXRecords	getMdexRecords()
protected MDEXState	getMDEXState()
java.lang.String	getName() get the DataSource's name
int	getNumCachedMDEXAttributes() Returns the number of attributes currently cached in the MDEXState.
java.util.List<com.endeca.mdex.lql_parser._2010.ParsedMetric>	getPredefinedMetrics(java.lang.String semanticKey) Given a semantic key, return all predefined metrics.
QueryState	getQueryState() Retrieve the current query state on this data source.
com.endeca.mdex.conversation.RecordKindOperator	getRecordKindOperator() Returns the appropriate RecordKindOperator for this data source or null if this data source should not use a RecordKindOperator.
protected RequestIds	getRequestIds()
java.util.List<com.endeca.mdex.sconfig._2010.types.SemanticEntity>	getSemanticEntities() Retrieves the list of semantic entities from the server.
java.util.List<com.endeca.mdex.sconfig._2010.types.SemanticEntity>	getSemanticEntities(boolean forceUncached) Retrieves the list of semantic entities from the server.
java.lang.String	getServiceURL() This method is only used when your data source and portlet support MDEX 7 and the Discovery Service API.
protected UserSession	getUserSession()
MDEXState.APIVersion	getVersion() Get what APIVersion this data source supports.
boolean	isAvailable()
boolean	isUpdatable()
com.endeca.mdex.lql_parser.types.ExpressionBase	parseLQLExpression(java.lang.String expression) Parse an LQL Filter string and return a parsed ExpressionBase object form of that string.
com.endeca.mdex.lql_parser.types.Query	parseLQLQuery(java.lang.String query, boolean validationEnabled) Parse an LQL Query string and return a parsed object form of that string.
com.endeca.mdex.sconfig._2010.types.PutEntityResponse	putSemanticEntity(com.endeca.mdex.sconfig._2010.types.SemanticEntity se) Replaces _all_ of the entity definitions in the MDEX with the list of entities passed as a parameter.
void	removeAttributeGroup(java.lang.String groupKey) Only for use with Discovery Service enabled datasources
void	resetQueryState() Reset the data source's query state to what it's initial state was.
void	setQueryState(QueryState newState) Set the state of this data source.
boolean	supportsConfigService()
boolean	supportsDiscoveryService()
boolean	supportsFeature(Feature f)
boolean	supportsLQLParserService()
boolean	supportsSConfigService()
java.lang.String	toString()
void	updateAttribute(Attribute uamAttribute) Only for use with Discovery Service enabled datasources Updates the specified attribute in the MDEX Note that this method is significantly different from createOrUpdateAttributeGroup(Group) in that it needs to first query the Config Service to obtain the complete record for the specified attribute, then modify it, and resubmit the updated PDR back to the Config Service.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

RECORD_KIND_PROPERTIES

public static final java.lang.String RECORD_KIND_PROPERTIES

See Also:

Constant Field Values

RECORD_KIND_DATA

public static final java.lang.String RECORD_KIND_DATA

See Also:

Constant Field Values

Constructor Detail

DataSource

public DataSource(javax.portlet.PortletRequest request,
                  java.lang.String dataSourceId)
           throws DataSourceException

Construct a DataSource instance referring to a particular data source. Most of the time, you should not need to instantiate your own DataSource instance. You should be able to call EndecaPortlet.getDataSource(PortletRequest) inside your portlet in most instances.

Parameters:

request - The current request object

dataSourceId - The id of the data source to represent

Throws:

DataSourceException

Method Detail

getUserSession

protected UserSession getUserSession()
                              throws UserSessionException

Throws:

UserSessionException

getMDEXState

protected MDEXState getMDEXState()

getRequestIds

protected RequestIds getRequestIds()

getName

public java.lang.String getName()

get the DataSource's name

Returns:

the name

getDescription

public java.lang.String getDescription()

get the DataSource's description

Returns:

the description

getId

public java.lang.String getId()

get the DataSource's ID

Returns:

the ID

getEventName

public javax.xml.namespace.QName getEventName()

Retrieve the event name that gets fired/listened for when this data source changes.

Returns:

The QName that represents all events related to state changes on this data source.

getVersion

public MDEXState.APIVersion getVersion()

Get what APIVersion this data source supports. For branching portlet code based on API support, we recommend using supportsDiscoveryService() instead of this method.

Returns:

the APIVersion of this data source.

supportsDiscoveryService

public boolean supportsDiscoveryService()

Returns:

true if this data source supports the MDEX 7 Discovery Service API, false otherwise. If the data source supports the conversation service, we assume it also supports the read only config service.

supportsConfigService

public boolean supportsConfigService()

Returns:

true if this data source supports the Config Service API, false otherwise.

supportsSConfigService

public boolean supportsSConfigService()

Returns:

true if this data source supports the Semantic Config Service API, false otherwise.

supportsLQLParserService

public boolean supportsLQLParserService()

Returns:

true if this data source supports the LQL Parser Service API, false otherwise.

getServiceURL

public java.lang.String getServiceURL()

This method is only used when your data source and portlet support MDEX 7 and the Discovery Service API.

Returns:

The service URL state for this data source

isAvailable

public boolean isAvailable()

Returns:

true if this data source is up and can run against the currently installed API, false otherwise. This returns true, even if the datasource is in read only mode and config updates are not available.

isUpdatable

public boolean isUpdatable()

Returns:

true if configuration updates are available for this datasource. True for DiscoveryService enabled datasources who can reach an updatable config service.

supportsFeature

public boolean supportsFeature(Feature f)

Returns:

true if this data source supports a given feature

getQueryState

public QueryState getQueryState()
                         throws DataSourceException

Retrieve the current query state on this data source. The value returned by this method will depend upon what MDEX State Manager you have configured.

Returns:

the query state

Throws:

DataSourceException

setQueryState

public void setQueryState(QueryState newState)
                   throws DataSourceException

Set the state of this data source. If this DataSource instance was instantiated with a PortletRequest instance that is not an ActionRequest instance, calling this method will throw an exception. The exact manner in which this method effects stored QueryState depends heavily on what MDEX State Manager you have configured.

Parameters:

newState - The new state to "push"

Throws:

DataSourceException

getInitialQueryState

public QueryState getInitialQueryState()
                                throws DataSourceException

Retrieve the initial QueryState on this data source, which is the QueryState defined in the data source's initial JSON configuration

Returns:

The query state initially configured on this data source

Throws:

DataSourceException

resetQueryState

public void resetQueryState()
                     throws DataSourceException

Reset the data source's query state to what it's initial state was.

Throws:

DataSourceException

execute

public QueryResults execute()
                     throws DataSourceException

Executes a query representing the data source's QueryState. Deprecated because, in the MDEX 7 Discovery Service, portlets will always need to modify the configuration in their QueryState to actually get results, so calling this method would result in empty results. This method will continue, however, to return expected results on presentation API MDEXs. This method applies security logic as managed by the MDEX Security Manager.

Returns:

The results of executing the query

Throws:

DataSourceException

execute

public QueryResults execute(QueryState queryState)
                     throws DataSourceException

Executes a query representing the QueryState. This method applies security logic as managed by the MDEX Security Manager.

Parameters:

queryState -

Returns:

The results of executing the query

Throws:

DataSourceException

getMDEXAttributes

public MDEXAttributeList getMDEXAttributes()
                                    throws DataSourceException

Retrieves a list of attributes available in the MDEX engine, by performing a key properties query and wrapping the results for convenience. This method is synchronized to ensure thread safety of the attribute cache

Returns:

the list of attributes

Throws:

DataSourceException

clearCachedMDEXAttributes

public void clearCachedMDEXAttributes()

Clears any session-cached attributes from the underlying MDEXState. Be cautious calling this method as clearing the cache will result in slower performance until the cache is repopulated. This method is synchronized to ensure thread safety of the attribute cache

getNumCachedMDEXAttributes

public int getNumCachedMDEXAttributes()

Returns the number of attributes currently cached in the MDEXState. Primarily used for testing to verify the cache.

Returns:

the number of attrs

getMDEXAttribute

public MDEXAttribute getMDEXAttribute(java.lang.String key)
                               throws DataSourceException

Convenience method to retrieve an attribute of a data source

Parameters:

key -

Returns:

the requested MDEXAttribute

Throws:

DataSourceException

getGlobalAttributeSettings

public AttributeSettings getGlobalAttributeSettings()
                                             throws DataSourceException

Gets the Global Unified Attribute Model for this datasource. If the model is not found in the MDEX State cache, it is retrieved from the engine and stored in the cache. This method uses Liferay Metadata persistence for MDEX6 datasources and Config Service for MDEX7 datasources.

Returns:

global AttributeSettings instance

Throws:

DataSourceException

clearCachedGlobalAttributeSettings

public void clearCachedGlobalAttributeSettings()

Only for use with Discovery Service enabled datasources Clears any session-cached Global UAM settings from the underlying MDEXState. Be cautious calling this method as clearing the cache will result in slower performance until the cache is repopulated. This method is synchronized to ensure thread safety of the attribute group cache

createOrUpdateAttributeGroup

public void createOrUpdateAttributeGroup(Group uamGroup)
                                  throws DataSourceException

Only for use with Discovery Service enabled datasources

Parameters:

uamGroup -

Throws:

DataSourceException

removeAttributeGroup

public void removeAttributeGroup(java.lang.String groupKey)
                          throws DataSourceException

Only for use with Discovery Service enabled datasources

Parameters:

groupKey -

Throws:

DataSourceException

updateAttribute

public void updateAttribute(Attribute uamAttribute)
                     throws DataSourceException,
                            javax.xml.parsers.ParserConfigurationException,
                            java.lang.UnsupportedOperationException

Only for use with Discovery Service enabled datasources Updates the specified attribute in the MDEX Note that this method is significantly different from createOrUpdateAttributeGroup(Group) in that it needs to first query the Config Service to obtain the complete record for the specified attribute, then modify it, and resubmit the updated PDR back to the Config Service. This has to be done because the Config Service requires a number of additional redundant properties to be set on the PDR record before it can be saved. It is not practical to store all of these properties for an Attribute in the UAM for large attribute sets.

Parameters:

uamAttribute - - Partially constructed UAM Attribute object. Has to contain the key and any properties that should be updated.

Throws:

DataSourceException

javax.xml.parsers.ParserConfigurationException

java.lang.UnsupportedOperationException

execute

public com.endeca.mdex.conversation.Results execute(com.endeca.mdex.conversation.Request query)
                                             throws DataSourceException

Applies security and executes query against the current request's State.

Parameters:

query - The query to execute

Returns:

The results of executing the query

Throws:

DataSourceException

executeConfigServiceUpdateOperation

public com.endeca.mdex.config.services.types.Results executeConfigServiceUpdateOperation(com.endeca.mdex.config.services.types.ConfigTransaction transaction)
                                                                                  throws DataSourceException

Executes update config service transactions

Parameters:

transaction - the ConfigTransaction to execute

Returns:

The results of executing the query

Throws:

DataSourceException

getSemanticEntities

public java.util.List<com.endeca.mdex.sconfig._2010.types.SemanticEntity> getSemanticEntities()
                                                                                       throws DataSourceException

Retrieves the list of semantic entities from the server. Available on both updatable MDEXes and readonly MDEXes

Returns:

a List of 0 to n semantic entities.

Throws:

DataSourceException

See Also:

getSemanticEntities(boolean)

getSemanticEntities

public java.util.List<com.endeca.mdex.sconfig._2010.types.SemanticEntity> getSemanticEntities(boolean forceUncached)
                                                                                       throws DataSourceException

Retrieves the list of semantic entities from the server. Available on both updatable MDEXes and readonly MDEXes

Returns:

a List of 0 to n semantic entities.

Throws:

DataSourceException

putSemanticEntity

public com.endeca.mdex.sconfig._2010.types.PutEntityResponse putSemanticEntity(com.endeca.mdex.sconfig._2010.types.SemanticEntity se)
                                                                        throws DataSourceException

Replaces _all_ of the entity definitions in the MDEX with the list of entities passed as a parameter. N.B. this means that any entity definitions not passed as an argument will be deleted from the MDEX. Available only on updatable MDEXes.

Parameters:

se - all of the semantic entities that will exist in the system after this put.

Returns:

information about the results of the put

Throws:

DataSourceException

deleteSemanticEntities

public com.endeca.mdex.sconfig._2010.types.DeleteEntitiesResponse deleteSemanticEntities(java.util.List<java.lang.String> entityKeys)
                                                                                  throws DataSourceException

Deletes all of the entity definitions in the MDEX with the passed keys. Available only on updatable MDEXes.

Parameters:

entityKeys - the list of keys to delete

Returns:

information about the results of the delete

Throws:

DataSourceException

parseLQLExpression

public com.endeca.mdex.lql_parser.types.ExpressionBase parseLQLExpression(java.lang.String expression)
                                                                   throws DataSourceException,
                                                                          LQLException

Parse an LQL Filter string and return a parsed ExpressionBase object form of that string. An example of a filter is "P_Price < 50". The syntax matches the syntax in the WHERE clause of an LQL Query expression, without the "WHERE". This method should parse and type-check the expression, so if you use an attribute that does not exist, it will throw a ParserFault. The returned objects can be used in the DataSourceFilter and SelectionFilter QueryFunctions. This method internally calls parseLQLFilter(String).

Parameters:

expression - String that represents the filter

Returns:

ExpressionBase object representation of the filter

Throws:

com.endeca.mdex.lql_parser._2010.ParserFault - if the filter has a syntax or type-checking error a ParserFault will be thrown

DataSourceException - any non-expected exception

LQLException

parseLQLQuery

public com.endeca.mdex.lql_parser.types.Query parseLQLQuery(java.lang.String query,
                                                            boolean validationEnabled)
                                                     throws DataSourceException,
                                                            LQLException

Parse an LQL Query string and return a parsed object form of that string. An example of a query is "RETURN results as SELECT AVG(P_Cost) as P_Cost WHERE P_Price < 50 GROUP BY P_Year". When validationEnabled is set to true, this method should parse and type-check the expression. So if you use an attribute that does not exist or do a comparison that using the wrong types it will throw a ParserFault. When validationEnabled is set to false, type-checking is disabled.

Parameters:

query - String that represents the query

validationEnabled - boolean to enable/disable query validation

Returns:

Query object representation of the query

Throws:

com.endeca.mdex.lql_parser._2010.ParserFault - if the filter has a syntax or type-checking error a ParserFault will be thrown

DataSourceException - any non-expected exception

LQLException

getPredefinedMetrics

public java.util.List<com.endeca.mdex.lql_parser._2010.ParsedMetric> getPredefinedMetrics(java.lang.String semanticKey)
                                                                                   throws DataSourceException,
                                                                                          LQLException

Given a semantic key, return all predefined metrics. This will throw a ParserFaultException if the passed key does not match any entity.

Parameters:

semanticKey - the string key to fetch

Returns:

a query object containing all predefined metrics in its select statements

Throws:

LQLException - if there is no entity with the provided key

DataSourceException - any non-expected exception

clearEntityCaches

public void clearEntityCaches()

Clears any information that is cached related to the entity information for this data source.

getRecordKindOperator

public com.endeca.mdex.conversation.RecordKindOperator getRecordKindOperator()

Returns the appropriate RecordKindOperator for this data source or null if this data source should not use a RecordKindOperator. The RecordKindOperator is dependent on the "mdexRecords" key in the data source's json definition and is used to filter the MDEX's result set to data records only, property records only, or all records.

Returns:

the appropriate RecordKindOperator for this data source or null

getMdexRecords

public MDEXState.MDEXRecords getMdexRecords()

Returns:

the records that the query will run against.

createDiscoveryServiceQuery

public com.endeca.mdex.conversation.Request createDiscoveryServiceQuery(QueryState state)
                                                                 throws DataSourceException

Create a Discovery Service Request instance from a query state, using the current request state.

Parameters:

state -

Returns:

The Request object

Throws:

DataSourceException

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object