com.exalead.papi.framework.connectors

Class Connector

java.lang.Object

com.exalead.papi.framework.connectors.Connector

All Implemented Interfaces:

com.exalead.mercury.component.CVComponent, ConnectorStatusExceptionInterface, ConnectorInterface

Direct Known Subclasses:

GenericMultiThreadedConnector

public abstract class Connector
extends java.lang.Object
implements ConnectorInterface, ConnectorInterface, ConnectorInterface, com.exalead.mercury.component.CVComponent

Top level class of connector. To implement a connector, you have to extend this class. You will typically implement at least the following methods:

• Constructor(YourConnectorConfig object): mandatory
• scan(PushAPI, String scanMode, Object scanModeconfig) : mandatory, the synchronization code entry point
• fetch(String uri) to allow fetching documents (preview, original document ..)
• getDocumentSecurityTokens(String uri) to fetch document-specific security tokens, for user ACL check (access credentials check)

Besides the @CVComponentConfigClass annotation class must reflect the types of the configuration object used in the constructor, and the configuration check class used to validate the configuration. A default configuration check class ConnectorConfigCheck.class is available, and attempt to use the historical com.exalead.papi.framework.connectors.ConnectorConfigCheckInterface interface on the configuration object.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	Connector.ConnectorNameThreadFactory A Thread factory that can have the name of spawned thread prefix customized.

Field Summary

Fields

Modifier and Type	Field and Description
protected ConnectorConfig	config Connector configuration.
static java.lang.String	DEFAULT_SCAN_MODE Default scan mode
protected PushAPI	papi Deprecated.

Constructor Summary

Constructors

Constructor and Description
Connector(ConnectorConfig config) Standard connector constructor
Connector(PushAPI papi, ConnectorConfig config) Deprecated. This constructor is deprecated. The preferred constructor is Connector(ConnectorConfig). See the 5.1 -> 6.0 connector migration guide

Method Summary

Modifier and Type	Method and Description
void	callBeforeDestruction() Override this method to do some task before the destruction of the connector
void	checkAbortingOperation() Deprecated. Use checkAbortingOperation member function instead.
void	checkAbortingOperation(java.lang.String scanMode) Checks the current connector status and, if an abort command was sent, throws an ConnectorAbortingException exception.
protected void	checkDataSourceAvailability() Deprecated. Provides the CheckConnectivity introspection query instead using the @{link IntrospectableComponent IntrospectableComponent} annotation.
boolean	checkSecurityTokens(java.lang.String uri, java.lang.String[] securityTokensUser) Check if a given user can access a given URI.
Document	fetch(java.lang.String uri) This method is used to retrieve document from the source when CloudView product needs it.
Document	fetch(java.lang.String uri, java.lang.String[] securityTokens, boolean shouldCheckSecurityTokens) This method is used to retrieve document from the source when CloudView product needs it.
ConnectorConfig	getConnectorConfig() Return the connector's configuration.
java.lang.String	getConnectorName()
MetaContainer	getDocumentSecurityTokens(java.lang.String uri) This method is used to retrieve security tokens of a document.
EndpointBuilder<? extends PushAPI>	getEndpointBuilder() A connector may require a specific end-point.
org.apache.log4j.Logger	getLogger() Get the root logger for this connector.
org.apache.log4j.Logger	getLogger(java.lang.String suffix) Get a sub-logger for this connector.
java.util.Set<java.lang.String>	getScanModes()
ConnectorState	getState() Deprecated. use @{link getState member function instead.
ConnectorState	getState(java.lang.String scanMode) Get state of the connector.
ConnectorStatus	getStatus() Deprecated. Use getStatus member function instead.
ConnectorStatus	getStatus(java.lang.String scanMode) Get status of the connector.
java.lang.Exception	getStatusException() Get exception of the connector which caused the connector to be in the ConnectorStatus.ERROR state.
void	init() Initialization method called by connector framework after construction
void	init(java.lang.String connectorName, boolean useSeparateStates) Internal initialization member method called by the connector framework.
void	onScanAborted() Deprecated. Implement onScanAborted member function instead.
void	onScanAborted(java.lang.String scanMode) Called by the framework when scan abort is requested.
void	onScanResumed() Deprecated. Use onScanResumed member function instead.
void	onScanResumed(java.lang.String scanMode) Called by the framework when scan resume is requested.
void	onScanSuspended() Deprecated. Implement onScanSuspended member function instead.
void	onScanSuspended(java.lang.String scanMode) Called by the framework when scan suspend is requested.
void	scan(PushAPI papi, java.lang.String scanMode, java.lang.Object scanModeConfig) This method is used to push (or synchronize) all documents from the source to CloudView product.
void	scratch(PushAPI papi) Clear connector state, default implementation: removes documents previously sent by the connector from CloudView index. clears checkpoints of the connector. Unless the connector is persisting additional data, there is not point to override this method.
void	selfAbortScan(java.lang.String reason) Deprecated. Use selfAbortScan(String) method instead.
void	selfAbortScan(java.lang.String scanMode, java.lang.String reason) Helper which can be called by the connector code to self-abort.
protected void	synchronizeDocuments(SynchronizationMode mode) Deprecated.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

papi

@Deprecated
protected PushAPI papi

Deprecated.

Use PushAPI given in parameter of the scan method.

config

protected ConnectorConfig config

Connector configuration.

DEFAULT_SCAN_MODE

public static final java.lang.String DEFAULT_SCAN_MODE

Default scan mode

See Also:

Constant Field Values

Constructor Detail

Connector

public Connector(ConnectorConfig config)
          throws java.lang.Exception

Standard connector constructor

Parameters:

config - A valid/filled configuration

Throws:

java.lang.Exception

Connector

@Deprecated
public Connector(PushAPI papi,
                             ConnectorConfig config)
                      throws java.lang.Exception

Deprecated. This constructor is deprecated. The preferred constructor is Connector(ConnectorConfig). See the 5.1 -> 6.0 connector migration guide

Standard constructor.

Parameters:

papi - PushAPI implementation

config - filled configuration

Throws:

java.lang.Exception

Method Detail

checkDataSourceAvailability

@Deprecated
protected void checkDataSourceAvailability()
                                                throws java.lang.Exception

Deprecated. Provides the CheckConnectivity introspection query instead using the @{link IntrospectableComponent IntrospectableComponent} annotation.

Check whether the underlying connector data source is available.

Throws:

java.lang.Exception - if the data source is unavailable in the current configuration state This method is to be overridden to do source configuration check ; to ensure that the source can provide data for reindexing

synchronizeDocuments

@Deprecated
protected void synchronizeDocuments(SynchronizationMode mode)
                                         throws java.lang.Exception

Deprecated.

This method is used to push (or synchronize) all documents from the source to CloudView product.

Throws:

java.lang.Exception

getScanModes

public final java.util.Set<java.lang.String> getScanModes()

Specified by:

getScanModes in interface ConnectorInterface

Returns:

Unmodifiable set of scan modes handled by this connector

scan

public void scan(PushAPI papi,
                 java.lang.String scanMode,
                 java.lang.Object scanModeConfig)
          throws java.lang.Exception

This method is used to push (or synchronize) all documents from the source to CloudView product.

Parameters:

papi - PushAPI used to dialog with CloudView

scanMode - Type of scan to perform. Is always DEFAULT_SCAN_MODE unless the connector declares additional scan modes with ConnectorCapabilities annotation.

scanModeConfig - Optional configuration given to the scanMode, according to ScanModeDefinition annotation.

Throws:

java.lang.Exception

fetch

public Document fetch(java.lang.String uri,
                      java.lang.String[] securityTokens,
                      boolean shouldCheckSecurityTokens)
               throws java.lang.Exception

This method is used to retrieve document from the source when CloudView product needs it.

Parameters:

uri - document identifier to retrieve

securityTokens - Security tokens of the user querying the document

shouldCheckSecurityTokens - If true, then the connector must send the document according to the security tokens given in parameters. For example the connector must return null if the user does not have credentials enough to view it, or only send the partial content the user is allowed to access.

Returns:

requested document

Throws:

java.lang.Exception - The default implementation throws a NoSuchMethodException exception ; (no preview nor fetch is possible in this case).

fetch

public Document fetch(java.lang.String uri)
               throws java.lang.Exception

This method is used to retrieve document from the source when CloudView product needs it.

Parameters:

uri - document identifier to retrieve

Returns:

requested document

Throws:

java.lang.Exception - The default implementation throws a NoSuchMethodException exception ; (no preview nor fetch is possible in this case).

getDocumentSecurityTokens

public MetaContainer getDocumentSecurityTokens(java.lang.String uri)
                                        throws java.io.IOException

This method is used to retrieve security tokens of a document. This method is only used for fetch, in the default implementation of "checkSecurityTokens".

Parameters:

uri - Uri of document

Returns:

Security tokens of this document. The default implementation returns a "Everybody" grant ACL, allowing to access all documents.

Throws:

java.io.IOException

scratch

public void scratch(PushAPI papi)
             throws java.lang.Exception

Clear connector state, default implementation:

• removes documents previously sent by the connector from CloudView index.
• clears checkpoints of the connector.

Unless the connector is persisting additional data, there is not point to override this method. This member method is called when you click on the "Clear documents" button from Administration Console or while executing the MAMI connect#clearConnector operation.

Parameters:

papi - The PushAPI to dialog with CloudView

Throws:

java.lang.Exception

getConnectorConfig

public ConnectorConfig getConnectorConfig()

Return the connector's configuration. The returned object can be casted to the connector's configuration class.

getStatus

public final ConnectorStatus getStatus(java.lang.String scanMode)

Get status of the connector. This function is used when managing an abort of a synchronization operation ; by checking that 'getStatus(scanMode) == ConnectorStatus.ABORTING'

Specified by:

getStatus in interface ConnectorInterface

Parameters:

scanMode - Type of the scan in progress

Returns:

the connector status

Since:

V6R2014.SP1

See Also:

ConnectorStatus}, #checkAbortingOperation(String) checkAbortingOperation} member function.

getStatus

@Deprecated
public ConnectorStatus getStatus()

Deprecated. Use getStatus member function instead.

Get status of the connector. This function is used when managing an abort of a synchronization operation ; by checking that 'getStatus(scanMode) == ConnectorStatus.ABORTING'

Returns:

the connector status

See Also:

ConnectorStatus, checkAbortingOperation()

getState

public final ConnectorState getState(java.lang.String scanMode)

Get state of the connector.

Specified by:

getState in interface ConnectorInterface

Parameters:

scanMode - Type of scan in progress

Returns:

State of the connector.

Since:

V6R2014.SP1

getState

@Deprecated
public ConnectorState getState()

Deprecated. use @{link getState member function instead.

Returns:

The state of the connector

checkAbortingOperation

public void checkAbortingOperation(java.lang.String scanMode)
                            throws ConnectorAbortingException

Checks the current connector status and, if an abort command was sent, throws an ConnectorAbortingException exception.

Specified by:

checkAbortingOperation in interface ConnectorInterface

Parameters:

scanMode - Type of scan in progress. This function is a helper which can be called by connector. It is not called by the framework.

Throws:

ConnectorAbortingException

Since:

V6R2014.SP1

checkAbortingOperation

@Deprecated
public void checkAbortingOperation()
                                        throws ConnectorAbortingException

Deprecated. Use checkAbortingOperation member function instead.

Checks the current connector status and, if an abort command was sent, throws an ConnectorAbortingException exception. This function is a helper which can be called by connector. It is not called by the framework.

Throws:

ConnectorAbortingException

getStatusException

public java.lang.Exception getStatusException()

Get exception of the connector which caused the connector to be in the ConnectorStatus.ERROR state.

Specified by:

getStatusException in interface ConnectorStatusExceptionInterface

Returns:

the connector exception, if any, or null otherwise

checkSecurityTokens

public boolean checkSecurityTokens(java.lang.String uri,
                                   java.lang.String[] securityTokensUser)

Check if a given user can access a given URI. The default implementation relies on the connector building a meta container with all security tokens for the URI

Parameters:

uri - ID of requested document

Returns:

true if final user is allowed to view document, false if not

Throws:

java.io.IOException

onScanAborted

public void onScanAborted(java.lang.String scanMode)
                   throws java.lang.Exception

Called by the framework when scan abort is requested. This method must not change the state of the connector, only wake up some calls which might be blocking. The scan will only be considered as aborted when the scan() method has returned.

Specified by:

onScanAborted in interface ConnectorInterface

Parameters:

scanMode - The type of scan to abort.

Throws:

java.lang.Exception

Since:

V6R2014.SP1

onScanAborted

@Deprecated
public void onScanAborted()
                               throws java.lang.Exception

Deprecated. Implement onScanAborted member function instead.

Description copied from interface: ConnectorInterface

Called by the framework when scan abort is requested. This method must not change the state of the connector, only wake up some calls which might be blocking. The scan will only be considered as aborted when the scan() method has returned.

Throws:

java.lang.Exception

onScanSuspended

public void onScanSuspended(java.lang.String scanMode)
                     throws java.lang.Exception

Called by the framework when scan suspend is requested. This method must not change the state of the connector, only wake up some calls which might be blocking. It is then the responsibility of the connector to set the status of the connector to SUSPENDED when effectively taken into account.

Specified by:

onScanSuspended in interface ConnectorInterface

Parameters:

scanMode - The type of scan to suspend.

Throws:

java.lang.Exception

Since:

V6R2014.SP1

onScanSuspended

@Deprecated
public void onScanSuspended()
                                 throws java.lang.Exception

Deprecated. Implement onScanSuspended member function instead.

Called by the framework when scan suspend is requested. This method must not change the state of the connector, only wake up some calls which might be blocking. It is then the responsibility of the connector to set the status of the connector to SUSPENDED when effectively taken into account.

Throws:

java.lang.Exception

onScanResumed

public void onScanResumed(java.lang.String scanMode)
                   throws java.lang.Exception

Called by the framework when scan resume is requested. This method must not change the state of the connector, only wake up some calls which might be blocking. It is then the responsibility of the connector to set the status of the connector to WORKING when effectively taken into account.

Specified by:

onScanResumed in interface ConnectorInterface

Parameters:

scanMode - The type of scan to resume.

Throws:

java.lang.Exception

Since:

V6R2014.SP1

onScanResumed

@Deprecated
public void onScanResumed()
                               throws java.lang.Exception

Deprecated. Use onScanResumed member function instead.

Called by the framework when scan resume is requested. This method must not change the state of the connector, only wake up some calls which might be blocking. It is then the responsibility of the connector to set the status of the connector to WORKING when effectively taken into account.

Throws:

java.lang.Exception

callBeforeDestruction

public void callBeforeDestruction()
                           throws java.lang.Exception

Override this method to do some task before the destruction of the connector

Throws:

java.lang.Exception

getConnectorName

public java.lang.String getConnectorName()

Specified by:

getConnectorName in interface ConnectorInterface

Returns:

Name of the connector instance.

Throws:

java.lang.Exception - If the member method is called before the init() method.

Since:

V6R2014.SP1

init

public final void init(java.lang.String connectorName,
                       boolean useSeparateStates)
                throws java.lang.Exception

Internal initialization member method called by the connector framework. Not meant to be used by the connector.

Parameters:

useSeparateStates -

Throws:

java.lang.Exception

init

public void init()
          throws java.lang.Exception

Initialization method called by connector framework after construction

Throws:

java.lang.Exception

getEndpointBuilder

public EndpointBuilder<? extends PushAPI> getEndpointBuilder()

A connector may require a specific end-point. End-point is the PushAPI which is at the end of the PushAPI filters and sends the data out of the connector server. Example of a specific end-point can be an end-point which is uses different source names at once, or does not communicate with HTTP.

Returns:

An instance of EndPointBuilder, or null if no specific end-point builder is required.

getLogger

public org.apache.log4j.Logger getLogger()

Get the root logger for this connector. This logger's name will include the connector name. All logging for this connector have to go through this logger for correct dispatch of messages.

getLogger

public org.apache.log4j.Logger getLogger(java.lang.String suffix)

Get a sub-logger for this connector. This logger's name will include the connector name and the specified suffix.

selfAbortScan

public void selfAbortScan(java.lang.String scanMode,
                          java.lang.String reason)

Helper which can be called by the connector code to self-abort.

Specified by:

selfAbortScan in interface ConnectorInterface

Parameters:

scanMode - scan to abort, given by the scan(PushAPI, String, Object) method.

reason - the reason why the abort was issues ; may be null

selfAbortScan

@Deprecated
public void selfAbortScan(java.lang.String reason)

Deprecated. Use selfAbortScan(String) method instead.

Helper which can be called by the connector code to self-abort.

Parameters:

reason - the reason why the abort was issued ; may be @c null