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

Constructor Summary

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

Method Summary

void	clearMetadataCaches() Clears the caches associated with this datasource.
void	clearViewCache() Deprecated. components shouldn't need to manually clear caches anymore
com.endeca.mdex.transaction.CommitOuterTransactionResponse	commitOuterTransaction(java.lang.String outerTransactionId) Commits an outer transaction.
com.endeca.mdex.conversation.Request	createDiscoveryServiceQuery(QueryState state) This method returns a query based on query state.
com.endeca.mdex.sconfig._2010.types.DeleteAllFilterRulesResponse	deleteAllFilterRules(java.lang.String outerTransactionId) Deletes all the filter rules from Endeca Server.
com.endeca.mdex.sconfig._2010.types.DeleteFilterRulesResponse	deleteFilterRules(java.util.List<java.lang.String> filterRuleKeysToDelete, java.lang.String outerTransactionId) Deletes a set of filter rules from Endeca Server ( outerTransactionId can be left null if this operation is not in a transaction).
int	deleteView(java.lang.String viewKey) Deletes the view referenced by the passed keys.
java.lang.String	determineStateName(QueryFunction f) Determines the correct state name for the given QueryFunction for use when applying the QueryFunction to the Request.
QueryResults	execute() Executes a query representing the data source's QueryState.
QueryResults	execute(QueryState queryState) Executes a query representing the QueryState.
com.endeca.mdex.config.services.types.Results	executeConfigServiceUpdateOperation(com.endeca.mdex.config.services.types.ConfigTransaction transaction) Executes update config service transactions
java.util.Collection<CollectionBaseView>	getAllCollections(java.util.Locale locale)
java.util.Collection<CollectionBaseView>	getAllCollections(java.util.Locale locale, boolean noRequests) Overriding method to getAllCollections(locale) that will return a null or empty collection rather than call out to an MDEX.
java.util.Collection<SemanticView>	getAllCollectionsAndSemanticViews(java.util.Locale locale) Get the full set of views, including both collection base views and custom semantic views.
java.util.List<com.endeca.mdex.sconfig._2010.types.FilterRule>	getAllFilterRules() Queries the Endeca Server for the full list of Filter Rules.
java.util.Collection<SemanticView>	getAllSemanticViews(java.util.Locale locale)
CollectionBaseView	getCollection(java.lang.String collectionKey, java.util.Locale locale) Get a CollectionBaseView that represents a collection base view.
SemanticView	getCollectionOrSemanticView(java.lang.String viewKey, java.util.Locale locale) Get a named SemanticView, which could be either a collection base view or a custom semantic view.
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() Deprecated. for temporary support while we migrate components to new Attribute UAM (com.endeca.portal.attributes.viewmodel.Attribute)
java.lang.String	getId() get the DataSource's ID
java.util.List<IncompleteCollectionState>	getIncompleteCollections()
QueryState	getInitialQueryState() Retrieve the base QueryState on this data source, which is the InitialQueryState + baseFilte
protected MDEXState	getMDEXState()
java.lang.String	getName() get the DataSource's name
java.util.Collection<PredefinedMetric>	getPredefinedMetrics(java.lang.String viewKey, java.util.Locale locale) Get all predefined metrics for a given view.
QueryState	getQueryState() Retrieve the current query state on this data source.
protected RequestIds	getRequestIds()
SemanticView	getSemanticView(java.lang.String viewKey, java.util.Locale locale) Get a custom SemanticView by the specified viewKey.
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	isIdle() Convenience method to check data domain idle status.
boolean	isOnline() Returns the cached availability of this data domain.
boolean	isUpdatable()
com.endeca.mdex.transaction.ListOuterTransactionResponse	listOuterTransaction() List outer transaction.
com.endeca.mdex.eql_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.eql_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.PutFilterRulesResponse	putFilterRules(java.util.List<com.endeca.mdex.sconfig._2010.types.FilterRule> filterRules, java.lang.String outerTransactionId) Adds or updates one or more filter rules on the Endeca Server.
int	putView(SemanticView sView) Adds or updates a custom semantic view or a collection.
void	resetQueryState() Reset the data source's query state to what it's initial state was.
void	resetVisibleQueryState() Removes only "visible" query filters from all collections.
void	resetVisibleQueryState(CollectionBaseView collection) Removes only "visible" query filters from a single collection.
com.endeca.mdex.transaction.RollBackOuterTransactionResponse	rollBackOuterTransaction(java.lang.String outerTransactionId) Rolls back an outer transaction.
void	setQueryState(QueryState newState) Set the state of this data source.
java.lang.String	startOuterTransaction() Starts a outer transaction.
boolean	supportsConfigService()
boolean	supportsDiscoveryService()
boolean	supportsFeature(Feature f)
boolean	supportsLQLParserService()
boolean	supportsSConfigService()
java.lang.String	toString()
com.endeca.mdex.sconfig._2010.types.ValidateEntityResponse	validateView(SemanticView sView) Validates a custom semantic view.

Methods inherited from class java.lang.Object

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

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.

isIdle

public boolean isIdle()

Convenience method to check data domain idle status.

Returns:

true if the domain is idle, false otherwise

See Also:

MDEXState.isIdle()

isOnline

public boolean isOnline()

Returns the cached availability of this data domain. This call relied on the previously established availability status, and will not re-test or update the status. It will not result in waking an idle data domain. If status refresh is desired, use the isAvailable() method.

Returns:

true if the data domain was available at last check

See Also:

MDEXState.isOnline()

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 base QueryState on this data source, which is the InitialQueryState + baseFilte

Returns:

The query state initially configured on this data source and base filter included

Throws:

DataSourceException

resetQueryState

public void resetQueryState()
                     throws DataSourceException

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

Throws:

DataSourceException

resetVisibleQueryState

public void resetVisibleQueryState()
                            throws DataSourceException

Removes only "visible" query filters from all collections. Used, for example, for Searchbox when search within is unchecked and search is submitted against "All Data".

Throws:

DataSourceException

resetVisibleQueryState

public void resetVisibleQueryState(CollectionBaseView collection)
                            throws DataSourceException

Removes only "visible" query filters from a single collection. Used, for example, by Breadcrumbs Reset and Searchbox when search within is unchecked and search is submitted against a single data set. Requirements of this variant of reset are as follows: 1) Invoking this method will do the equivalent of clicking the delete "x" next to each item in the visible breadcrumbs. That is, it does NOT clear all of the filter state for all data sets. It clears the items you're seeing (which may, if they came through a refinement rule, clear some filters from other data sets). 2) Invoking this method also resets base filter(s) to their default state. There is only one base filter per data set, but a second may have come through a refinement rule (which will be reset, too, on its source data set). 3) Only visible filters will be removed. Any filters in the query state that the breadcrumbs does not know how to display will be left alone. In other words, if you've used a deep link to apply a DataSourceFilter or SelectionFilter to your query state, it will not be removed by this reset method. It won't be removable at all. It'll just stick with you for the duration of your session. Similarly, if a user created/deployed a custom query function (e.g. MySpecialFooBarLineItemFilter extends QueryFunction), that, too, would not be removed since it's not something we consider "visible" and know how to display. You'd have to deploy your own component to show those and allow adding/editing/removing those.

Parameters:

collection - the CollectionBaseView from whose query state to remove visible filters

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

clearMetadataCaches

public void clearMetadataCaches()

Clears the caches associated with this datasource. Because attributes, attribute groups, and entities are inter-dependent, if you update attributes or attribute groups, you should use this method to update all three items so they are consistent with each other.

clearViewCache

public void clearViewCache()

Deprecated. components shouldn't need to manually clear caches anymore

Clears any information that is cached related to the entity information for this data source. If you are modifying entity groups, you should call DataSource.clearMetadataCaches instead of this method so the attribute group cache is cleared in addition to the entity cache.

getGlobalAttributeSettings

public AttributeSettings getGlobalAttributeSettings()
                                             throws DataSourceException

Deprecated. for temporary support while we migrate components to new Attribute UAM (com.endeca.portal.attributes.viewmodel.Attribute)

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. TODO: this will be removed once components migrate off of it

Returns:

global AttributeSettings instance

Throws:

DataSourceException

getCollection

public CollectionBaseView getCollection(java.lang.String collectionKey,
                                        java.util.Locale locale)
                                 throws KeyNotFoundException,
                                        DataSourceException

Get a CollectionBaseView that represents a collection base view. The collection cache is initialized if necessary.

Parameters:

collectionKey - key of the mdex collection sought

Returns:

matching CollectionBaseView

Throws:

KeyNotFoundException - if the collection with the specified key is not found

DataSourceException - if there was a query error when getting collection metadata

getAllCollections

public java.util.Collection<CollectionBaseView> getAllCollections(java.util.Locale locale)
                                                           throws DataSourceException

Returns:

a Collection of all the cached CollectionBaseViews

Throws:

DataSourceException - if there was a query error when getting collection metadata

getAllCollections

public java.util.Collection<CollectionBaseView> getAllCollections(java.util.Locale locale,
                                                                  boolean noRequests)
                                                           throws DataSourceException

Overriding method to getAllCollections(locale) that will return a null or empty collection rather than call out to an MDEX.

Parameters:

locale -

noRequests - boolean to toggle using

Returns:

Throws:

DataSourceException

getSemanticView

public SemanticView getSemanticView(java.lang.String viewKey,
                                    java.util.Locale locale)
                             throws KeyNotFoundException,
                                    DataSourceException

Get a custom SemanticView by the specified viewKey. The cache of view information is initialized if necessary.

Parameters:

viewKey - key of the mdex view sought

Returns:

matching semantic view

Throws:

KeyNotFoundException - if the view with the specified key is not found

DataSourceExcpetion - if there was a query error when getting view metadata

DataSourceException

getAllSemanticViews

public java.util.Collection<SemanticView> getAllSemanticViews(java.util.Locale locale)
                                                       throws DataSourceException

Returns:

a Collection of all the cached custom SemanticViews

Throws:

DataSourceException - if there was a query error when getting view metadata

getCollectionOrSemanticView

public SemanticView getCollectionOrSemanticView(java.lang.String viewKey,
                                                java.util.Locale locale)
                                         throws KeyNotFoundException,
                                                DataSourceException

Get a named SemanticView, which could be either a collection base view or a custom semantic view.

Parameters:

viewKey - key of the collection or semantic view sought

Returns:

matching view

Throws:

KeyNotFoundException - if the view with the specified key is not found

DataSourceExcpetion - if there was a query error when getting view metadata

DataSourceException

getAllCollectionsAndSemanticViews

public java.util.Collection<SemanticView> getAllCollectionsAndSemanticViews(java.util.Locale locale)
                                                                     throws DataSourceException

Get the full set of views, including both collection base views and custom semantic views.

Returns:

a Collection a SemanticViews

Throws:

DataSourceExcpetion - if there was a query error when getting view metadata

DataSourceException

getAllFilterRules

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

Queries the Endeca Server for the full list of Filter Rules.

Returns:

List of FilterRules objects.

Throws:

DataSourceException

putFilterRules

public com.endeca.mdex.sconfig._2010.types.PutFilterRulesResponse putFilterRules(java.util.List<com.endeca.mdex.sconfig._2010.types.FilterRule> filterRules,
                                                                                 java.lang.String outerTransactionId)
                                                                          throws DataSourceException

Adds or updates one or more filter rules on the Endeca Server.

Parameters:

filterRules: - a list of FilterRule objects to add/update on the server

outerTransactionId: - outerTransactionId when outer transaction is used; can be left NULL if this operation is not part of a transaction.

Returns:

response object indicating results of the put operation

Throws:

DataSourceException

deleteFilterRules

public com.endeca.mdex.sconfig._2010.types.DeleteFilterRulesResponse deleteFilterRules(java.util.List<java.lang.String> filterRuleKeysToDelete,
                                                                                       java.lang.String outerTransactionId)
                                                                                throws DataSourceException

Deletes a set of filter rules from Endeca Server ( outerTransactionId can be left null if this operation is not in a transaction).

Parameters:

filterRuleKeysToDelete: - list of Strings indicating the keys of the filter rules to delete.

outerTransactionId: - outerTransactionId when outer transaction is used; can be left NULL if this operation is not part of a transaction.

Returns:

response object indicating results of the delete operation

Throws:

DataSourceException

deleteAllFilterRules

public com.endeca.mdex.sconfig._2010.types.DeleteAllFilterRulesResponse deleteAllFilterRules(java.lang.String outerTransactionId)
                                                                                      throws DataSourceException

Deletes all the filter rules from Endeca Server.

Parameters:

outerTransactionId: - outerTransactionId when outer transaction is used; can be left NULL if this operation is not part of a transaction.

Returns:

response object indicating results of the delete operation

Throws:

DataSourceException

startOuterTransaction

public java.lang.String startOuterTransaction()
                                       throws java.lang.Exception

Starts a outer transaction. A lock is defined in MDEXState class and used to synchronize simultaneous requests to start transactions. If multiple start-transaction requests are being simultaneously fired for a same Endeca server (corresponding to the same MDEXState class), except for the first request, all the others would be suspended until the first transaction is committed or rolled back. In case that multiple app servers are trying to start transactions on a same Endca server simultaneously, Endeca server will handle the conflicts. It will return an outer transaction Id to the first server/request and return Exceptions/TransactionFaults to the other servers/requests, until the first transaction is committed or rolled back.

Returns:

outerTransactionId

Throws:

java.lang.Exception

commitOuterTransaction

public com.endeca.mdex.transaction.CommitOuterTransactionResponse commitOuterTransaction(java.lang.String outerTransactionId)
                                                                                  throws java.lang.Exception

Commits an outer transaction.

Returns:

response object indicating results of the commit operation

Throws:

java.lang.Exception

rollBackOuterTransaction

public com.endeca.mdex.transaction.RollBackOuterTransactionResponse rollBackOuterTransaction(java.lang.String outerTransactionId)
                                                                                      throws java.lang.Exception

Rolls back an outer transaction.

Returns:

response object indicating results of the rollback operation

Throws:

java.lang.Exception

listOuterTransaction

public com.endeca.mdex.transaction.ListOuterTransactionResponse listOuterTransaction()
                                                                              throws java.lang.Exception

List outer transaction.

Returns:

response object indicating the in-process outer transaction if any

Throws:

java.lang.Exception

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

deleteView

public int deleteView(java.lang.String viewKey)
               throws KeyNotFoundException,
                      DataSourceException

Deletes the view referenced by the passed keys. Available only on updatable MDEXes. Passing in locale from current request so any error messages come back in the user's current language.

Parameters:

viewKey - references the view to delete

Returns:

number of views deleted

Throws:

KeyNotFoundException

DataSourceException

putView

public int putView(SemanticView sView)
            throws DataSourceException

Adds or updates a custom semantic view or a collection.

Parameters:

sView - a SemanticView or CollectionBaseView to add or update

Returns:

number of added or updated views

Throws:

DataSourceException

validateView

public com.endeca.mdex.sconfig._2010.types.ValidateEntityResponse validateView(SemanticView sView)
                                                                        throws DataSourceException

Validates a custom semantic view.

Parameters:

sView - a SemanticView to validate

Returns:

the ValidateEntityResponse

Throws:

DataSourceException

parseLQLExpression

public com.endeca.mdex.eql_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.eql_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.eql_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.eql_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.Collection<PredefinedMetric> getPredefinedMetrics(java.lang.String viewKey,
                                                                   java.util.Locale locale)
                                                            throws KeyNotFoundException,
                                                                   DataSourceException

Get all predefined metrics for a given view.

Parameters:

viewKey - key of a view whose metrics are sought

Returns:

the List of PredefinedMetric objects

Throws:

KeyNotFoundException - if there is no semantic view matching the provided key

DataSourceException - if a query error is encountered loading view metadata

createDiscoveryServiceQuery

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

This method returns a query based on query state.

Parameters:

state -

Returns:

Request

Throws:

DataSourceException

determineStateName

public java.lang.String determineStateName(QueryFunction f)
                                    throws DataSourceException,
                                           KeyNotFoundException

Determines the correct state name for the given QueryFunction for use when applying the QueryFunction to the Request.

Parameters:

f - a QueryFunction to potentially associate with a named state

Returns:

the name of the state appropriate for this QueryFunction or null if no state name should be set

Throws:

DataSourceException - if there was a problem retrieving Collections or SemanticViews underpinning this DataSource

KeyNotFoundException - if the QueryFunction references an unknown view key

getIncompleteCollections

public java.util.List<IncompleteCollectionState> getIncompleteCollections()

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object