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

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.mdex.conversation.Request	createDiscoveryServiceQuery(QueryState state, com.endeca.mdex.conversation.Request requestState) Create a Discovery Service Request instance from a query state, given a 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() Deprecated.
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 underlying MDEX State's QueryState and the current RequestState.
QueryResults	execute(QueryState queryState, com.endeca.mdex.conversation.Request requestState) Executes a query represented by a QueryState and a RequestState.
com.endeca.mdex.conversation.Results	execute(com.endeca.mdex.conversation.Request query) Applies security and executes query against the current request's FilterState.
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
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
QueryState	getQueryState() Retrieve the current query state on this data source.
com.endeca.mdex.conversation.Request	getRequestState() 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.

getRequestState

public com.endeca.mdex.conversation.Request getRequestState()

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

Returns:

The Request state for 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.

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

@Deprecated
public QueryResults execute()
                     throws DataSourceException

Deprecated.

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,
                            com.endeca.mdex.conversation.Request requestState)
                     throws DataSourceException

Executes a query represented by a QueryState and a RequestState. If we're using the ENE presentation API, the entire state is encapsulated in the QueryState, so requestState is ignored. This method applies security logic as managed by the MDEX Security Manager.

Parameters:

queryState -

requestState -

Returns:

The results of executing the query

Throws:

DataSourceException

execute

public QueryResults execute(QueryState queryState)
                     throws DataSourceException

Executes a query representing the underlying MDEX State's QueryState and the current RequestState. If we're using the ENE presentation API, the entire state is encapsulated in 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

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 FilterState.

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,
                                                                        com.endeca.mdex.conversation.Request requestState)
                                                                 throws DataSourceException

Create a Discovery Service Request instance from a query state, given a request state

Parameters:

state - the query state

requestState - the conversation service

Returns:

the Discovery Service request

Throws:

DataSourceException

See Also:

createENEQuery(QueryState)

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