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

Constructors

Constructor and Description
DataSource(javax.portlet.PortletRequest request)
DataSource(javax.portlet.PortletRequest request, long groupId)
DataSource(javax.portlet.PortletRequest request, MDEXState mdexState)
DataSource(javax.portlet.PortletRequest request, java.lang.String dataSourceId) Deprecated. use DataSource(PortletRequest) instead
DataSource(javax.portlet.PortletRequest request, java.lang.String[] boundDataSets)
DataSource(javax.portlet.PortletRequest request, java.lang.String dataSourceId, long groupId) Deprecated. use DataSource(PortletRequest, long) instead

Method Summary

Methods

Modifier and Type	Method and Description
void	addCollectionData(java.lang.String collectionKey, java.util.List<Record> recordList) Add records to a collection One of the assignments in each 'Record' object should have the unique identifier property key/value.
void	addCollectionName(java.lang.String collectionName, java.lang.String newCollectionName)
void	clearMetadataCaches() Clears the caches associated with this datasource.
void	clearMetadataCaches(boolean refresh)
void	clearViewCache() Deprecated. components shouldn't need to manually clear caches anymore
boolean	collectionExists(java.lang.String collectionKey)
com.endeca.mdex.transaction.types.CommitOuterTransactionResponse	commitOuterTransaction(java.lang.String outerTransactionId) Commits an outer transaction.
java.lang.String	convertLQLToString(com.endeca.mdex.eql_parser.types.Node node) Converts an EQL node into a readable EQL string.
com.endeca.mdex.conversation.types.Request	createDiscoveryServiceQuery(QueryState state) This method returns a query based on query state.
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.conversation.types.Results	execute(com.endeca.mdex.conversation.types.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.util.Collection<CollectionBaseView>	getAllCollections()
java.util.Collection<SemanticView>	getAllCollectionsAndSemanticViews() Get the full set of views, including both collection base views and custom semantic views.
java.util.Collection<SemanticView>	getAllCollectionsAndSemanticViews(boolean includeNonActive) Get the full set of views, including both collection base views and custom semantic views.
java.util.Collection<SemanticView>	getAllSemanticViews()
java.util.Collection<SemanticView>	getAllSemanticViews(boolean includeNonActive)
CollectionBaseView	getCollection(java.lang.String collectionKey) Get a CollectionBaseView that represents a collection base view.
SemanticView	getCollectionOrSemanticView(java.lang.String viewKey) Get a named SemanticView, which could be either a collection base view or a custom semantic view.
java.lang.String	getDescription() Deprecated. Display of data source should no longer be necessary
java.lang.String	getId() Deprecated. Display of data source should no longer be necessary
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() Deprecated. Display of data source should no longer be necessary
java.util.Collection<PredefinedMetric>	getPredefinedMetrics(java.lang.String viewKey) Get all predefined metrics for a given view.
QueryState	getQueryState() Retrieve the current query state on this data source.
MDEXState.ReadOnlyCause	getReadOnlyCause() Deprecated. data source is always updatable now
protected RequestIds	getRequestIds()
SemanticView	getSemanticView(java.lang.String viewKey) Get a custom SemanticView by the specified viewKey.
java.lang.String	getServiceURL() Return the service URL state for this data source.
protected UserSession	getUserSession()
void	induceEntityCacheFlush() Issues an empty Conversation Service request with an EQLConfig against this project's entity namespace in order for the Dgraph Gateway to refresh its entity cache.
boolean	isAvailable()
boolean	isOnline() Returns the cached availability of this data domain.
boolean	isUpdatable() Deprecated. data source is always updatable now
com.endeca.mdex.transaction.types.ListOuterTransactionResponse	listOuterTransaction() List outer transaction.
void	moveCollectionName(java.lang.String collectionNameToMove, java.lang.String targetCollectionName)
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.QueryWithAttributeMetadata	parseLQLQuery(java.lang.String query, boolean validationEnabled) Parse an EQL Query string and return a parsed object form of that string.
int	putView(SemanticView sView) Adds or updates a custom semantic view or a collection.
void	removeCollectionName(java.lang.String collectionName)
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.types.RollBackOuterTransactionResponse	rollBackOuterTransaction(java.lang.String outerTransactionId) Rolls back an outer transaction.
boolean	semanticViewExists(java.lang.String viewKey)
void	setQueryState(QueryState newState) Set the state of this data source.
java.lang.String	startOuterTransaction() Starts a outer transaction.
java.lang.String	toString() Deprecated. remove code that serialized DataSource to JSON
void	updateCollectionData(java.lang.String collectionKey, java.util.List<Record> recordList) Update records in a collection The 'recordSpecifier' in 'Record' objects should have the unique identifier property key/value.
com.endeca.endeca_server.sconfig.types.ValidateEntitiesResponse	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

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

Deprecated. use DataSource(PortletRequest) instead

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

DataSource

public DataSource(javax.portlet.PortletRequest request)
           throws DataSourceException

Throws:

DataSourceException

DataSource

public DataSource(javax.portlet.PortletRequest request,
          MDEXState mdexState)
           throws DataSourceException

Throws:

DataSourceException

DataSource

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

Deprecated. use DataSource(PortletRequest, long) instead

Throws:

DataSourceException

DataSource

public DataSource(javax.portlet.PortletRequest request,
          java.lang.String[] boundDataSets)
           throws DataSourceException

Throws:

DataSourceException

DataSource

public DataSource(javax.portlet.PortletRequest request,
          long groupId)
           throws DataSourceException

Throws:

DataSourceException

Method Detail

getUserSession

protected UserSession getUserSession()
                              throws UserSessionException

Throws:

UserSessionException

getMDEXState

protected MDEXState getMDEXState()

getRequestIds

protected RequestIds getRequestIds()

getName

@Deprecated
public java.lang.String getName()

Deprecated. Display of data source should no longer be necessary

get the DataSource's name

Returns:

the name

getDescription

@Deprecated
public java.lang.String getDescription()

Deprecated. Display of data source should no longer be necessary

get the DataSource's description

Returns:

the description

getId

@Deprecated
public java.lang.String getId()

Deprecated. Display of data source should no longer be necessary

get the DataSource's ID

Returns:

the ID

getServiceURL

public java.lang.String getServiceURL()

Return the service URL state for this data source.

Returns:

The service URL state for this data source

isAvailable

public boolean isAvailable()

Returns:

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

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

@Deprecated
public boolean isUpdatable()

Deprecated. data source is always updatable now

Returns:

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

getReadOnlyCause

@Deprecated
public MDEXState.ReadOnlyCause getReadOnlyCause()

Deprecated. data source is always updatable now

Return reason for MDEXState being in read-only

Returns:

getQueryState

public QueryState getQueryState()
                         throws DataSourceException

Retrieve the current query state on this data source.

Returns:

the query state

Throws:

DataSourceException

setQueryState

public void setQueryState(QueryState newState)
                   throws DataSourceException

Set the state of this data source. 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. 2) Invoking this method also resets base filter(s) to their default state. There is only one base filter per 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 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. 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.

clearMetadataCaches

public void clearMetadataCaches(boolean refresh)
                         throws DataSourceException

Throws:

DataSourceException

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.

collectionExists

public boolean collectionExists(java.lang.String collectionKey)

semanticViewExists

public boolean semanticViewExists(java.lang.String viewKey)

getCollection

public CollectionBaseView getCollection(java.lang.String collectionKey)
                                 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()
                                                           throws DataSourceException

Returns:

a Collection of all the cached CollectionBaseViews

Throws:

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

getSemanticView

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

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

Parameters:

request - TODO

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()
                                                       throws DataSourceException

Returns:

a Collection of all the cached custom SemanticViews, including active and non-active views.

Throws:

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

getAllSemanticViews

public java.util.Collection<SemanticView> getAllSemanticViews(boolean includeNonActive)
                                                       throws DataSourceException

Parameters:

Whether - to include non-active views or not.

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)
                                         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()
                                                                     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

getAllCollectionsAndSemanticViews

public java.util.Collection<SemanticView> getAllCollectionsAndSemanticViews(boolean includeNonActive)
                                                                     throws DataSourceException

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

Parameters:

Whether - to include non-active views or not.

Returns:

a Collection a SemanticViews

Throws:

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

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.types.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.types.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.types.ListOuterTransactionResponse listOuterTransaction()
                                                                                    throws java.lang.Exception

List outer transaction.

Returns:

response object indicating the in-process outer transaction if any

Throws:

java.lang.Exception

execute

public com.endeca.mdex.conversation.types.Results execute(com.endeca.mdex.conversation.types.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

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

updateCollectionData

public void updateCollectionData(java.lang.String collectionKey,
                        java.util.List<Record> recordList)
                          throws KeyNotFoundException,
                                 DataSourceException

Update records in a collection The 'recordSpecifier' in 'Record' objects should have the unique identifier property key/value.

Parameters:

collectionKey -

recordList -

Throws:

KeyNotFoundException

DataSourceException

addCollectionData

public void addCollectionData(java.lang.String collectionKey,
                     java.util.List<Record> recordList)
                       throws KeyNotFoundException,
                              DataSourceException

Add records to a collection One of the assignments in each 'Record' object should have the unique identifier property key/value.

Parameters:

collectionKey -

recordList -

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.endeca_server.sconfig.types.ValidateEntitiesResponse validateView(SemanticView sView)
                                                                             throws DataSourceException

Validates a custom semantic view.

Parameters:

sView - a SemanticView to validate

Returns:

the ValidateEntityResponse

Throws:

DataSourceException

addCollectionName

public void addCollectionName(java.lang.String collectionName,
                     java.lang.String newCollectionName)
                       throws DataSourceException

Throws:

DataSourceException

moveCollectionName

public void moveCollectionName(java.lang.String collectionNameToMove,
                      java.lang.String targetCollectionName)
                        throws DataSourceException

Throws:

DataSourceException

removeCollectionName

public void removeCollectionName(java.lang.String collectionName)
                          throws DataSourceException

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.types.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.QueryWithAttributeMetadata parseLQLQuery(java.lang.String query,
                                                                        boolean validationEnabled)
                                                                          throws DataSourceException,
                                                                                 LQLException

Parse an EQL 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:

QueryWithAttributeMetadata object containing the parsed EQLQuery AST as well as metadata about the attributes defined by the query

Throws:

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

DataSourceException - any non-expected exception

LQLException

convertLQLToString

public java.lang.String convertLQLToString(com.endeca.mdex.eql_parser.types.Node node)

Converts an EQL node into a readable EQL string.

Parameters:

node - Any node, from a full query to a simple expression

Returns:

EQL string

getPredefinedMetrics

public java.util.Collection<PredefinedMetric> getPredefinedMetrics(java.lang.String viewKey)
                                                            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.types.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()

induceEntityCacheFlush

public void induceEntityCacheFlush()
                            throws DataSourceException

Issues an empty Conversation Service request with an EQLConfig against this project's entity namespace in order for the Dgraph Gateway to refresh its entity cache. This should be called after an SConfig operation that changes the entities in some way.

Throws:

DataSourceException

toString

@Deprecated
public java.lang.String toString()

Deprecated. remove code that serialized DataSource to JSON

Overrides:

toString in class java.lang.Object