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	clearCachedMDEX7AttributeGroups() Clears any session-cached attribute groups from the underlying MDEXState.
void	clearCachedMDEXAttributes() Clears any session-cached attributes from the underlying MDEXState.
com.endeca.mdex.conversation.Request	createDiscoveryServiceQuery(QueryState state) Create a Discovery Service Request instance from a query state, using the current request state.
com.endeca.navigation.ENEQuery	createENEQuery() Create an ENEQuery object from the data source's current state.
com.endeca.navigation.ENEQuery	createENEQuery(QueryState state) Create an ENEQuery object based on the specified query state
QueryResults	execute() Executes a query representing the data source's QueryState.
com.endeca.navigation.ENEQueryResults	execute(com.endeca.navigation.ENEQuery query) Applies security filters as managed by the MDEX Security Manager and executes query
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.
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.
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
AttributeGroup	getMDEX7AttributeGroup(java.lang.String key) Convenience method to retrieve an attribute group from a discovery service data source
AttributeGroupLinkedMap	getMDEX7AttributeGroups() Retrieves a list of attribute groups available in the MDEX engine, by performing a Discovery Service query and wrapping the results for convenience.
AttributeGroupLinkedMap	getMDEX7AttributeGroups(java.util.List<java.lang.String> keys) Returns the specified groups from the data source.
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.
protected MDEXState	getMDEXState()
java.lang.String	getName() get the DataSource's name
int	getNumCachedMDEX7AttributeGroups() Returns the number of attribute groups currently cached in the MDEXState.
int	getNumCachedMDEXAttributes() Returns the number of attributes currently cached in the MDEXState.
QueryState	getQueryState() Retrieve the current query state on this data source.
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()
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	supportsDiscoveryService()
boolean	supportsENEQuery()
boolean	supportsFeature(Feature f)
java.lang.String	toString()

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

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 supportsENEQuery() or supportsDiscoveryService() instead of this method.

Returns:

the APIVersion of this data source.

supportsENEQuery

public boolean supportsENEQuery()

Returns:

true if this data source supports the ENE Presentation API, false otherwise.

supportsDiscoveryService

public boolean supportsDiscoveryService()

Returns:

true if this data source supports the MDEX 7 Discovery 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 API, false otherwise.

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

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

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.

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.

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:

Throws:

DataSourceException

getMDEX7AttributeGroups

public AttributeGroupLinkedMap getMDEX7AttributeGroups()
                                                throws DataSourceException

Retrieves a list of attribute groups available in the MDEX engine, by performing a Discovery Service query and wrapping the results for convenience. Only supported on Discovery Service datasources.

Returns:

AttributeGroups

Throws:

DataSourceException

getMDEX7AttributeGroups

public AttributeGroupLinkedMap getMDEX7AttributeGroups(java.util.List<java.lang.String> keys)
                                                throws DataSourceException

Returns the specified groups from the data source. Looks in cache if it has been populated already; otherwise queries the MDEX Engine.

Parameters:

keys - the list of keys of the requested groups

Returns:

the groups

Throws:

DataSourceException

getMDEX7AttributeGroup

public AttributeGroup getMDEX7AttributeGroup(java.lang.String key)
                                      throws DataSourceException

Convenience method to retrieve an attribute group from a discovery service data source

Parameters:

group - key

Returns:

attribute group

Throws:

DataSourceException

clearCachedMDEX7AttributeGroups

public void clearCachedMDEX7AttributeGroups()

Clears any session-cached attribute groups from the underlying MDEXState. Be cautious calling this method as clearing the cache will result in slower performance until the cache is repopulated.

getNumCachedMDEX7AttributeGroups

public int getNumCachedMDEX7AttributeGroups()

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

Returns:

the number of attribute groups in the cache

createENEQuery

public com.endeca.navigation.ENEQuery createENEQuery()
                                              throws DataSourceException

Create an ENEQuery object from the data source's current state. Should be used if, for whatever reason, you need to directly manipulate an ENEQuery and can't accomplish what you need to do. This is discouraged: QueryState instances should be manipulated instead of ENEQuery instances whenever possible.

Returns:

the ENEQuery state

Throws:

DataSourceException

See Also:

QueryState, createDiscoveryServiceQuery(QueryState)

createENEQuery

public com.endeca.navigation.ENEQuery createENEQuery(QueryState state)
                                              throws DataSourceException

Create an ENEQuery object based on the specified query state

Parameters:

state -

Returns:

the ENEQuery state

Throws:

DataSourceException

See Also:

createENEQuery(), createDiscoveryServiceQuery(QueryState)

execute

public com.endeca.navigation.ENEQueryResults execute(com.endeca.navigation.ENEQuery query)
                                              throws DataSourceException

Applies security filters as managed by the MDEX Security Manager and executes query

Parameters:

query - the query to execute.

Returns:

the presentation API results

Throws:

DataSourceException

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

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

See Also:

createENEQuery(QueryState)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object