org.opends.server.backends

Class ProxyBackend

java.lang.Object

org.opends.server.api.Backend<ProxyBackendCfg>

org.opends.server.backends.ProxyBackend

All Implemented Interfaces:

ConfigurationChangeListener<ProxyBackendCfg>, RequestHandler, HealthStatusProvider

public final class ProxyBackend
extends Backend<ProxyBackendCfg>
implements ConfigurationChangeListener<ProxyBackendCfg>

Implements the proxy backend, i.e. an LDAP endpoint able to forward LDAP requests to remote LDAP servers.

The proxy backend forwards requests to remote servers using load balancers.

Implementation detail: the proxy backend uses a hierarchy of load balancers / connections factories that are setup this way: if the proxy backend is configured for distribution (with more than one partition):

 Load Balancers - reference counted (one for bind operations + another one for other operations)
    |
    +--- newFixedSizeDistributionLoadBalancer (for n partitions)
      |
      +--- n newFailoverLoadBalancer (each fails over primary and secondary servers)
        |
        +--- 2 new*RequestLoadBalancer (Affinity or LeastRequests - one for primary servers, one for secondary
          |    servers)
          |
          +--- newCachedConnectionPool - reference counted
            |
            +--- LdapConnectionFactory
 

Otherwise, the proxy backend is configured for direct proxying (with only one partition):

 Load Balancers - reference counted (one for bind operations + another one for other operations)
    |
    +--- newFailoverLoadBalancer (over primary and secondary servers)
      |
      +--- 2 new*RequestLoadBalancer (Affinity or LeastRequests - one for primary servers, one for secondary servers)
        |
        +--- newCachedConnectionPool - reference counted
          |
          +--- LdapConnectionFactory
 

Note: Some load balancers/connection factories are reference counted, in order to ease managing their lifecycle and to avoid disturbing clients. When a change affects the load balancers/connection factories, the proxy backend needs to rebuild a whole new load balancer hierarchy in order to make use of them. However, LDAP is a connected protocol, thus closing connections should be avoided when there is no need to. As a consequence some connection factories/load balancers are reference counted to ensure they are closed only when they are no longer referenced.

Constructor Summary

Constructors

Constructor and Description
ProxyBackend()

Method Summary

Modifier and Type	Method and Description
ConfigChangeResult	applyConfigurationChange(ProxyBackendCfg newConfig) Applies the configuration changes to this change listener.
void	configureBackend(ProxyBackendCfg cfg, ServerContext serverContext) Configure this backend based on the information in the provided configuration.
void	deregisterBackendMonitor() Deregisters the backend monitor of this backend.
void	finalizeBackend() Performs any necessary work to finalize this backend.
Set<Dn>	getBaseDNs() Retrieves the set of base-level DNs that may be used within this backend.
Set<String>	getSupportedControls() Retrieves the OIDs of the controls that may be supported by this backend.
Set<String>	getSupportedFeatures() Retrieves the OIDs of the features that may be supported by this backend.
Flowable<Response>	handle(org.forgerock.services.context.Context context, Request request) Returns a Flowable representing the asynchronous Response of the given request.
boolean	isConfigurationAcceptable(ProxyBackendCfg config, List<LocalizableMessage> unacceptableReasons, ServerContext serverContext) Indicates whether the provided configuration is acceptable for this backend.
boolean	isConfigurationChangeAcceptable(ProxyBackendCfg config, List<LocalizableMessage> unacceptableReasons) Indicates whether the proposed change to the configuration is acceptable to this change listener.
boolean	isPublicBackend() Indicates whether the base DNs of this backend should be considered public or private.
void	openBackend() Opens this backend based on the information provided when the backend was configured.
void	registerBackendMonitor() Registers a backend monitor for this backend.

Methods inherited from class org.opends.server.api.Backend

getBackendID, getHealthStatus, setBackendID, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

ProxyBackend

public ProxyBackend()

Method Detail

handle

public Flowable<Response> handle(org.forgerock.services.context.Context context,
                                 Request request)

Description copied from interface: RequestHandler

Returns a Flowable representing the asynchronous Response of the given request.

Successful responses (@see ResultCode.isExceptional() must be provided to the subscriber through the Subscriber.onNext(Object) method. All erroneous responses (e.g: no such object) must be published to the subscriber through the Subscriber.onError(Throwable) method.

Specified by:

handle in interface RequestHandler

Parameters:

context - The request context.

request - The request.

Returns:

A Flowable of zero or several Response to be returned to the caller.

configureBackend

public void configureBackend(ProxyBackendCfg cfg,
                             ServerContext serverContext)
                      throws ConfigException

Description copied from class: Backend

Configure this backend based on the information in the provided configuration. When the method returns, the backend will have been configured (ready to be opened) but still unable to process operations.

Specified by:

configureBackend in class Backend<ProxyBackendCfg>

Parameters:

cfg - The configuration of this backend.

serverContext - The server context for this instance

Throws:

ConfigException - If there is an error in the configuration.

openBackend

public void openBackend()
                 throws ConfigException

Description copied from class: Backend

Opens this backend based on the information provided when the backend was configured. It also should open any underlying storage and register all suffixes with the server.

Specified by:

openBackend in class Backend<ProxyBackendCfg>

Throws:

ConfigException - If an unrecoverable problem arises while opening the backend.

See Also:

Backend.configureBackend(C, org.opends.server.core.ServerContext)

getBaseDNs

public Set<Dn> getBaseDNs()

Description copied from class: Backend

Retrieves the set of base-level DNs that may be used within this backend.

Specified by:

getBaseDNs in class Backend<ProxyBackendCfg>

Returns:

The set of base-level DNs that may be used within this backend.

getSupportedControls

public Set<String> getSupportedControls()

Description copied from class: Backend

Retrieves the OIDs of the controls that may be supported by this backend.

Overrides:

getSupportedControls in class Backend<ProxyBackendCfg>

Returns:

The OIDs of the controls that may be supported by this backend.

getSupportedFeatures

public Set<String> getSupportedFeatures()

Description copied from class: Backend

Retrieves the OIDs of the features that may be supported by this backend.

Overrides:

getSupportedFeatures in class Backend<ProxyBackendCfg>

Returns:

The OIDs of the features that may be supported by this backend.

finalizeBackend

public void finalizeBackend()

Description copied from class: Backend

Performs any necessary work to finalize this backend. The backend must be an opened backend, so do not use this method on backends where only configureBackend() has been called. This may be called during the Directory Server shutdown process or if a backend is disabled with the server online. It must not return until the backend is closed.

This method may not throw any exceptions. If any problems are encountered, then they may be logged but the closure should progress as completely as possible.

Specified by:

finalizeBackend in class Backend<ProxyBackendCfg>

isPublicBackend

public boolean isPublicBackend()

Description copied from class: Backend

Indicates whether the base DNs of this backend should be considered public or private.

This method also controls the visibility of the associated naming contexts. i.e. if any base DN of this backend is a naming context, then it will be public or private, based on the value returned by this method.

Reminder: Public naming contexts are returned when querying the root DSE entry.

Specified by:

isPublicBackend in class Backend<ProxyBackendCfg>

Returns:

true if this backend's baseDNs could be exposed as a public naming context, false if they must remain private naming contexts.

isConfigurationAcceptable

public boolean isConfigurationAcceptable(ProxyBackendCfg config,
                                         List<LocalizableMessage> unacceptableReasons,
                                         ServerContext serverContext)

Description copied from class: Backend

Indicates whether the provided configuration is acceptable for this backend. It should be possible to call this method on an uninitialized backend instance in order to determine whether the backend would be able to use the provided configuration.

Overrides:

isConfigurationAcceptable in class Backend<ProxyBackendCfg>

Parameters:

config - The backend configuration for which to make the determination.

unacceptableReasons - A list that may be used to hold the reasons that the provided configuration is not acceptable.

serverContext - this Directory Server instance's server context

Returns:

true if the provided configuration is acceptable for this backend, or false if not.

isConfigurationChangeAcceptable

public boolean isConfigurationChangeAcceptable(ProxyBackendCfg config,
                                               List<LocalizableMessage> unacceptableReasons)

Description copied from interface: ConfigurationChangeListener

Indicates whether the proposed change to the configuration is acceptable to this change listener.

Specified by:

isConfigurationChangeAcceptable in interface ConfigurationChangeListener<ProxyBackendCfg>

Parameters:

config - The new configuration containing the changes.

unacceptableReasons - A list that can be used to hold messages about why the provided configuration is not acceptable.

Returns:

Returns true if the proposed change is acceptable, or false if it is not.

applyConfigurationChange

public ConfigChangeResult applyConfigurationChange(ProxyBackendCfg newConfig)

Description copied from interface: ConfigurationChangeListener

Applies the configuration changes to this change listener.

Specified by:

applyConfigurationChange in interface ConfigurationChangeListener<ProxyBackendCfg>

Parameters:

newConfig - The new configuration containing the changes.

Returns:

Returns information about the result of changing the configuration.

registerBackendMonitor

public void registerBackendMonitor()

Description copied from class: Backend

Registers a backend monitor for this backend.

Overrides:

registerBackendMonitor in class Backend<ProxyBackendCfg>

deregisterBackendMonitor

public void deregisterBackendMonitor()

Description copied from class: Backend

Deregisters the backend monitor of this backend.

Overrides:

deregisterBackendMonitor in class Backend<ProxyBackendCfg>