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	OMIT_SYSTEM_RECORDS_FILTER
static java.lang.String	OMIT_SYSTEM_RECORDS_NAME
static java.lang.String	ONLY_PROPERTY_RECORDS_FILTER
static java.lang.String	ONLY_PROPERTY_RECORDS_NAME

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.
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() Deprecated.
com.endeca.navigation.ENEQuery	createENEQuery(QueryState state) Deprecated.
void	createOrUpdateAttributeGroup(Group uamGroup) Only for use with Discovery Service enabled datasources
QueryResults	execute() Executes a query representing the data source's QueryState.
com.endeca.navigation.ENEQueryResults	execute(com.endeca.navigation.ENEQuery query) Deprecated.
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	executeConfigServiceReadOperation(com.endeca.mdex.config.services.types.ReadOnlyConfigTransaction transaction) Applies security and executes read only Config Service transactions
com.endeca.mdex.config.services.types.Results	executeConfigServiceUpdateOperation(com.endeca.mdex.config.services.types.ConfigTransaction transaction) Applies security and executes read only and update config cervice 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.
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()
boolean	isUpdatable()
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	supportsDiscoveryService()
boolean	supportsENEQuery() Deprecated.
boolean	supportsFeature(Feature f)
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

ONLY_PROPERTY_RECORDS_NAME

public static final java.lang.String ONLY_PROPERTY_RECORDS_NAME

See Also:

Constant Field Values

ONLY_PROPERTY_RECORDS_FILTER

public static final java.lang.String ONLY_PROPERTY_RECORDS_FILTER

See Also:

Constant Field Values

OMIT_SYSTEM_RECORDS_NAME

public static final java.lang.String OMIT_SYSTEM_RECORDS_NAME

See Also:

Constant Field Values

OMIT_SYSTEM_RECORDS_FILTER

public static final java.lang.String OMIT_SYSTEM_RECORDS_FILTER

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

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

@Deprecated
public boolean supportsENEQuery()

Deprecated.

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. If the data source supports the conversation service, we assume it also supports the read only config service.

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. Always true for ENEQuery datasources, and 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:

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:

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:

uamGroup -

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

createENEQuery

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

Deprecated.

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

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

Deprecated.

Create an ENEQuery object based on the specified query state

Parameters:

state -

Returns:

the ENEQuery state

Throws:

DataSourceException

See Also:

createENEQuery(), createDiscoveryServiceQuery(QueryState)

execute

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

Deprecated.

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

executeConfigServiceReadOperation

public com.endeca.mdex.config.services.types.Results executeConfigServiceReadOperation(com.endeca.mdex.config.services.types.ReadOnlyConfigTransaction transaction)
                                                                                throws DataSourceException

Applies security and executes read only Config Service transactions

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

Applies security and executes read only and update config cervice transactions

Parameters:

query - The query to execute

Returns:

The results of executing the query

Throws:

DataSourceException

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

See Also:

createENEQuery(QueryState)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object