Package com.pingidentity.sources

Interface CustomDataSourceDriver

All Superinterfaces:

ConfigurableDriver, ConfigurablePlugin

public interface CustomDataSourceDriver
extends ConfigurableDriver

This interface provides the methods necessary to successfully create a CustomDataSourceDriver. Classes derived from this interface can be used to access non-standard or unique data stores. Default implementation of JDBC and LDAP data stores exist. This interface provides access to all other types of data stores.

This interface defines methods to test the connection to the unique data store testConnection()}, perform the actual retrieval of information retrieveValues(Collection, SimpleFieldList) and provide a list of available fields to the user getAvailableFields().

A companion descriptor class CustomDataSourceDriverDescriptor has been created to allow the user to set fields that can be used to filter data during the retrieveValues(Collection, SimpleFieldList) method call. To utilize the CustomDataSourceDriverDescriptor class, send an instance of this class in the ConfigurableDriver.getSourceDescriptor() method call. If the default SourceDescriptor class is used, the user will not be provided the ability to filter result sets.

See Also:

SimpleFieldList

Method Summary

Modifier and Type	Method	Description
default String	encodeFilterFieldParam(String filterFieldName, String paramToEncode)	This method is called by PingFederate prior to retrieving information from the specified driver.
List<String>	getAvailableFields()	PingFederate will take the list returned from this method, and display the field names as individual checkbox items.
Map<String,Object>	retrieveValues(Collection<String> attributeNamesToFill, SimpleFieldList filterConfiguration)	This method is called by PingFederate when a connection (either IdP or SP) needs to retrieve information from the specified driver.
boolean	testConnection()	This method is used to determine whether the connection managed by a specific driver instance is available.

Methods inherited from interface com.pingidentity.sources.ConfigurableDriver

configure, getSourceDescriptor

Method Detail

testConnection

boolean testConnection()

This method is used to determine whether the connection managed by a specific driver instance is available. This method is used by the PingFederate UI prior to rendering to determine whether the driver information should be editable.

Returns:

true if the connection is available

retrieveValues

Map<String,Object> retrieveValues(Collection<String> attributeNamesToFill,
                                        SimpleFieldList filterConfiguration)
                                 throws CustomDataSourceDriverException

This method is called by PingFederate when a connection (either IdP or SP) needs to retrieve information from the specified driver. This method is expected to return a map containing the resulting values. The values in this map can be java.lang objects like strings or numbers, or they can be wrapped as instances of AttributeValue. For best compatibility with PingFederate features and external systems, values should either be strings or collections of strings. For string collections, it's recommended to wrap the collection as an AttributeValue using AttrValueSupport.make(Collection).

Parameters:

attributeNamesToFill - An array of names to retrieve values for. In the JDBC paradigm, these would be column names.

filterConfiguration - A SimpleFieldList list of filter criteria to use when retrieve values. May be null if no filter configuration is provided. These fields are described by the CustomDataSourceDriverDescriptor class.

Returns:

A map, keyed by values from the attributeNamesToFill array, that contains values retrieved by the custom driver. If no data matches the filter criteria, then an empty Map should be returned. Null should not be returned.

Throws:

CustomDataSourceDriverException - If an error occurs while retrieving values.

getAvailableFields

List<String> getAvailableFields()

PingFederate will take the list returned from this method, and display the field names as individual checkbox items. The user can select those fields for which they want values, and then map those selected field names against adapter contracts. During execution, the names that the user has mapped will be sent to the retrieveValues(Collection, SimpleFieldList) method.

Returns:

A list of available fields to display to the user.

encodeFilterFieldParam

default String encodeFilterFieldParam(String filterFieldName,
                                      String paramToEncode)

This method is called by PingFederate prior to retrieving information from the specified driver. It calls this method to encode any source attribute values used by filters that are applied during information retrieval. For example, if the filter field is applied in a URL, then the driver may wish to URL encode the filter field.

The default implementation of this method returns the same parameter without any encoding

Parameters:

filterFieldName - the String name of the filter field

paramToEncode - the String value of the source attribute that needs to be encoded

Returns:

the encoded String value of the parameter to encode