Programming Guides › Programming Guide for Java Connector Server › High Level Connector Design Considerations › API

API

When designing a connector, consider the following when deciding which technology or API the Connector uses to connect to the endpoint:

• The ApacheDS framework on top of which the Java CS is built allocates threads from a configured pool to all incoming requests, regardless of which connectors they target. Therefore your connector must be written in a threadsafe manner, as a single connector instance can ask to process any number of requests concurrently.

  This makes using connection pool especially attractive, as connections to the endpoint system are often intended to be used by only one thread at a time. However, there can be other objects that you need to guard using synchronized methods or blocks in your connector code too.

  Note: For more information, see the configuration.maxThreads setting in conf/SAMPLE.server_jcs.properties.

• Is the chosen technology API compatible with the notion of connection pooling?

  If so, is it best to use the Java CS framework support for writing a pool, or are their particular advantages to using native connection pooling support, if it is available?

  • Connection pools have two main advantages:
    • Improving scalability and throughput when creating new connections is expensive, as the pool allows existing connections to be reused rather than created and destroyed for each use.
    • Resource throttling, the pool imposes a limit so that the number of connections does not grow in an unbounded way, even under sever loading.
• If your connector deals with any multivalued attributes, then use the Java CS to deal with LDAP MODIFY requests, where each modification has a mode chosen from:
  • REPLACE–Full list of new values is provided
  • ADD–List of values added to existing list is provided
  • REMOVE –List of values removed from existing list is provided. A null list means that the attribute is removed.

  This means that for multivalued attributes that are modified, determine whether the chosen technology API best suits updating using:

  • forceReplaceMode=REPLACE metadata setting for each attribute. Your connector is provided with the complete list of new values, regardless of the mode chosen by the client application.
  • forceReplaceMode=DELTA–Separate lists of items added or removed are provided in all cases.

  There is also a value forceReplaceMode=DELTA_WITH_REMOVES_FIRST which behaves the same as DELTA except that the REMOVE delta is sent to your connector before the ADD delta (which suits some APIs better).There is also forceReplaceMode=PRESERVE which disables all modification item rewriting for an attribute on which it is set.

• Are you allowed to bundle the necessary libraries with your connector?

  If you are not allowed to bundle the libraries, document the location of the libraries and the location where they are copied, so the Java CS can find them, with any additional configuration burden on the Java CS.

• Your connector can use its resource or directory to include any configuration files and utilities, or both, which are not directly part of the connector code. If your connector is a port of an existing connector, and migration is required, we recommend that you put migration scripts here.
• Does the chosen technology or API use JNI and therefore require the Java CS to have runtime access to non-Java libraries through the Java Native Interface (JNI) API?

  Note: Given the risks of using JNI, unless you have a high level of confidence in the library concerned, host the connector in a separate Java CS instance to help ensure that if any JNI problems cause the host Java CS to crash, other connectors are not impacted.

• Does the connector need to use multiple APIs to communicate with the endpoint? If so, the design and implementation are greatly complicated, particularly in the areas of connection pooling, resiliency, and search result streaming.