com.ca.jcs
Interface Connector

All Superinterfaces:

Activatable, CachingConnector, OpProcessorStyleFactory, Partition

All Known Implementing Classes:

BaseConnector, JDBCMetaConnector, JNDIMetaConnector, MetaConnector, ORAMetaConnector, SDKMetaConnector, SDKWSMetaConnector, StubMetaConnector

public interface Connector
extends Partition, Activatable, OpProcessorStyleFactory, CachingConnector

Root interface for connectors.

See Also:

BaseConnector

Field Summary

static int

STATE_DELETING When ORed into stateFlags, signifies that connector is in the process of being permanently deleted.

Fields inherited from interface org.apache.directory.server.core.partition.Partition

ALIAS_ATTRIBUTE, ALIAS_OBJECT

Method Summary

void	activate() Activate the connector making it visible to the outside world.
Attributes	convertAttributesFromConnector(Name connDn, String ldapDnStr, MetaObjectClassMapping classMap, Set<String> requestedConnAttrIds, Attributes connAttrs, boolean strict) Called to convert query results from connector-speak to LDAP, can also provide a useful override point when implementing a calculated attribute which may optionally need to be included for doLookUp() and doSearch() results.
LdapDN	convertDNFromConnector(Name connDn, MetaObjectClassMapping leafClassMap, SearchResult sr, Boolean isRelative) Convert a DN (distinguished name) from connector-speak to it's LDAP equivalent, where this is required for: Each search result returned by list() or search() Any attribute values stored on the connector end that contain DN values.
Name	convertDNToConnector(LdapDN ldapDn) Convert provided ldap DN to connector-speak (note: naming attributes are sometimes ambiguous).
Name	convertDNToConnector(LdapDN ldapDn, boolean queryCache) Convert provided ldap DN to connector-speak, possibly using cache if configured and active.
ConnectionManager	createConnectionManager()
ObjectInfo	createObjectInfo() Allows implementation of ObjectInfo extension, if required for a connector.
TransactionManager	createTransactionManager() Optionally implemented method, where tranactions are supported for a particular connector technology and configuration.
void	deactivate() This method is called when the target object is no longer needed and should tidy-up any connections / resources it holds.
Attributes	getAttributes()
AttributeStyleOpProcessor	getAttributeStyleOpProcessor()
ConnectionManager	getConnectionManager()
ConnectorConfig	getConnectorConfig()
String	getLdapExceptionPrefix() Used by the framework and concrete connectors to distinguish exceptions orginating from within the JCS from those of the host container (ApacheDS).
String	getLdapNamingAttr()
String	getLdapObjectClass()
Logger	getLogger()
MethodStyleOpProcessor	getMethodStyleOpProcessor()
String	getName()
Partition	getPartition()
ScriptStyleOpProcessor	getScriptStyleOpProcessor()
int	getStateFlags()
LdapDN	getStoredSuffix() We duplicate the suffix known to this partition's configuration so that a connector is better encapsulated.
TransactionManager	getTransactionManager()
ConnectorType	getType()
boolean	isActivated()
void	modifyAttributes(ModificationItem[] items) Modify existing attribute settings.
void	postProcessLdapSearchResult(Name connDn, MetaObjectClassMapping classMap, Set<String> requestedConnAttrIds, Attributes connAttrs, SearchResult sr) Plug-in point for connectors that must customise search result representation after DN and attributes have been fully mapped to LDAP, for instance to handle of connector-specific DN manipulation such as that required to handle "Unique OU" for LND connector.
void	setAttributes(Attributes attrs) Provide attributes to connector so that it can use them in conjunction with its type's metadata to initialise (eg it can establish its connection pool using these two sources of data).
void	setAttributeStyleOpProcessor(AttributeStyleOpProcessor asp)
void	setConnectionManager(ConnectionManager mgr)
void	setConnectorConfig(ConnectorConfig connectorConfig)
void	setLdapNamingAttr(String ldapNamingAttr)
void	setLdapObjectClass(String ldapObjectClass)
void	setMethodStyleOpProcessor(MethodStyleOpProcessor obp)
void	setName(String name)
void	setScriptStyleOpProcessor(ScriptStyleOpProcessor obp)
void	setStateFlags(int flags)
void	setStoredSuffix(LdapDN storedSuffix)
void	setTransactionManager(TransactionManager mgr)
void	setType(ConnectorType type)

Methods inherited from interface org.apache.directory.server.core.partition.Partition

add, bind, delete, destroy, getSuffix, getUpSuffix, hasEntry, init, isInitialized, isSuffix, list, lookup, lookup, modify, modify, modifyRn, move, move, search, sync, unbind

Methods inherited from interface com.ca.jcs.processor.OpProcessorStyleFactory

createAttributeStyleOpProcessor, createMethodStyleOpProcessor, createScriptStyleOpProcessor

Methods inherited from interface com.ca.jcs.cache.CachingConnector

getCacheableStatus, getCacheManager, isCachingActive, isCachingRequired, setCacheManager, setCachingRequired

Field Detail

STATE_DELETING

static final int STATE_DELETING

When ORed into stateFlags, signifies that connector is in the process of being permanently deleted.

See Also:

Constant Field Values

Method Detail

getLdapExceptionPrefix

String getLdapExceptionPrefix()

Used by the framework and concrete connectors to distinguish exceptions orginating from within the JCS from those of the host container (ApacheDS).

getConnectorConfig

ConnectorConfig getConnectorConfig()

setConnectorConfig

void setConnectorConfig(ConnectorConfig connectorConfig)

getAttributes

Attributes getAttributes()

getLogger

Logger getLogger()

setAttributes

void setAttributes(Attributes attrs)
                   throws NamingException

Provide attributes to connector so that it can use them in conjunction with its type's metadata to initialise (eg it can establish its connection pool using these two sources of data). These attributes are persisted so that connector creation can be triggered by a modify of a single field.

Parameters:

attrs - Attributes passed to add() or

Throws:

NamingException

modifyAttributes

void modifyAttributes(ModificationItem[] items)
                      throws NamingException

Modify existing attribute settings.

Throws:

NamingException

getName

String getName()

setName

void setName(String name)

getType

ConnectorType getType()

setType

void setType(ConnectorType type)

isActivated

boolean isActivated()

activate

void activate()
              throws NamingException

Activate the connector making it visible to the outside world. Should respect ConnectorConfig.isLazyConnect() where this is possible and makes sense for the connector (for instance some connectors need to contact the managed system immediately and consequently can not support a "lazy connection" mode). The connector's attributes must provide all the data needed to establish a connection to the managed system, in addition to any other data important to the connector (such as current logging level etc).

Specified by:

activate in interface Activatable

Throws:

NamingException

deactivate

void deactivate()
                throws NamingException

Description copied from interface: Activatable

This method is called when the target object is no longer needed and should tidy-up any connections / resources it holds.

Specified by:

deactivate in interface Activatable

Throws:

NamingException

getStateFlags

int getStateFlags()

setStateFlags

void setStateFlags(int flags)

createConnectionManager

ConnectionManager createConnectionManager()
                                          throws NamingException

Returns:

Mandatory simplistic connection manager for the connector, which is hopefully implemented by developer of concrete connector as a facade to a connection pool where possible.

Throws:

NamingException

getConnectionManager

ConnectionManager getConnectionManager()

setConnectionManager

void setConnectionManager(ConnectionManager mgr)

createTransactionManager

TransactionManager createTransactionManager()

Optionally implemented method, where tranactions are supported for a particular connector technology and configuration.

getTransactionManager

TransactionManager getTransactionManager()

setTransactionManager

void setTransactionManager(TransactionManager mgr)

getLdapObjectClass

String getLdapObjectClass()

setLdapObjectClass

void setLdapObjectClass(String ldapObjectClass)

getLdapNamingAttr

String getLdapNamingAttr()

setLdapNamingAttr

void setLdapNamingAttr(String ldapNamingAttr)

getPartition

Partition getPartition()

getStoredSuffix

LdapDN getStoredSuffix()

We duplicate the suffix known to this partition's configuration so that a connector is better encapsulated.

convertDNToConnector

Name convertDNToConnector(LdapDN ldapDn)
                          throws NamingException

Convert provided ldap DN to connector-speak (note: naming attributes are sometimes ambiguous).

Throws:

NamingException

convertDNToConnector

Name convertDNToConnector(LdapDN ldapDn,
                          boolean queryCache)
                          throws NamingException

Convert provided ldap DN to connector-speak, possibly using cache if configured and active.

Throws:

NamingException

convertDNFromConnector

LdapDN convertDNFromConnector(Name connDn,
                              MetaObjectClassMapping leafClassMap,
                              SearchResult sr,
                              Boolean isRelative)
                              throws NamingException,
                                     LdapNoSuchAttributeException

Convert a DN (distinguished name) from connector-speak to it's LDAP equivalent, where this is required for:

1. Each search result returned by list() or search()
2. Any attribute values stored on the connector end that contain DN values.

Parameters:

connDn - DN to be converted.

leafClassMap - Mappings for objectClass which DN is a references an instance of. In the presence of ambiguous naming attributes this may be critical in performing the DN resolution, and consequently search results must always include an "objectClass=" attribute to disambiguate. In the second case above (connector-speak DN values) the author of the metadata is responsible for providing the objectClass name when creating a DNPropertyConverter for the containing attribute.

sr - Connector-speak search results provided when available (i.e. when stepping through search results as opposed to converting DNs in an association attribute like group.members), as some connectors may need to know some attribute values in order to compute LDAP DN (for example UniqueOU support for LND). When null means DN is absolute otherwise sr.isRelative() is used to determine if a relative, rather then an absolute, DN returned. Note either way that any specified connectorBaseDn is ignored (see convertDNToConnector(LdapDN) for discussion of why). Expect absolute case will be useful for query results only, and that persistently stored DNs will always be relative.

isRelative - If sr is null then this argument can be used used to specify whether connDn is relative or absolute (see comments on searchResult above), otherwise it should be null.

Returns:

connDn converted to LDAP.

Throws:

NamingException

LdapNoSuchAttributeException

convertAttributesFromConnector

Attributes convertAttributesFromConnector(Name connDn,
                                          String ldapDnStr,
                                          MetaObjectClassMapping classMap,
                                          Set<String> requestedConnAttrIds,
                                          Attributes connAttrs,
                                          boolean strict)
                                          throws NamingException

Called to convert query results from connector-speak to LDAP, can also provide a useful override point when implementing a calculated attribute which may optionally need to be included for doLookUp() and doSearch() results.

Parameters:

connDn - Connector-speak DN for target object for which attributes are being converted to LDAP.

ldapDnStr - LDAP equivalent to connDn

classMap - Information about the class for the target object.

requestedConnAttrIds - Set containing all attribute names requested by the client, attribute names will have the exact case as specified for their connectorMapTo values in the metadata.

connAttrs - All attribute that need to be converted to LDAP (this method may choose to add more).

strict - True if attributes with empty values should cause an exception rather then just being logged and deleted.

Returns:

Attributes mapped to LDAP.

Throws:

NamingException

createObjectInfo

ObjectInfo createObjectInfo()

Allows implementation of ObjectInfo extension, if required for a connector.

postProcessLdapSearchResult

void postProcessLdapSearchResult(Name connDn,
                                 MetaObjectClassMapping classMap,
                                 Set<String> requestedConnAttrIds,
                                 Attributes connAttrs,
                                 SearchResult sr)
                                 throws NamingException

Plug-in point for connectors that must customise search result representation after DN and attributes have been fully mapped to LDAP, for instance to handle of connector-specific DN manipulation such as that required to handle "Unique OU" for LND connector. Unless the DN itself needs special handling then overriding convertAttributesFromConnector(Name, String, MetaObjectClassMapping, Set, Attributes, boolean) may suffice.

Parameters:

connDn - Connector-speak DN for target object whose attributes have been converted to LDAP in sr.

classMap - Information about the class for the target object.

requestedConnAttrIds - Set containing all attribute names requested by the client, attribute names will have the exact case as specified for their connectorMapTo values in the metadata.

connAttrs - Original connector-speak attributes prior to being converted to LDAP and placed in sr.

sr - Search result, with LDAP DN and LDAP-speak attributes.

Throws:

NamingException

setStoredSuffix

void setStoredSuffix(LdapDN storedSuffix)

getAttributeStyleOpProcessor

AttributeStyleOpProcessor getAttributeStyleOpProcessor()

setAttributeStyleOpProcessor

void setAttributeStyleOpProcessor(AttributeStyleOpProcessor asp)

getMethodStyleOpProcessor

MethodStyleOpProcessor getMethodStyleOpProcessor()

setMethodStyleOpProcessor

void setMethodStyleOpProcessor(MethodStyleOpProcessor obp)

getScriptStyleOpProcessor

ScriptStyleOpProcessor getScriptStyleOpProcessor()

setScriptStyleOpProcessor

void setScriptStyleOpProcessor(ScriptStyleOpProcessor obp)