UnboundID Server SDK

Processing Internal Operations

When writing extensions to operate within the server, it is often necessary to be able to process operations in the server in order to perform queries and/or make updates. Although you could use LDAP to establish connections and process operations like any other client, this is both problematic and inefficient. A much better approach to the problem is to perform internal operations. Using internal operations within extensions offers a number of benefits over invoking external operations, including:

• There is no need to know the address of the server, what port it is using, how to authenticate, whether to use a secure connection, etc. You can easily obtain an internal connection authenticated as either an internal root user or as any specified user.
  
  
• Internal operations are more efficient because there is no network transfer or protocol handling, and there is no go through the work queue or have the request handed off between threads.
  
  
• Internal operations may be used to perform updates that are not allowed for external clients. For example, internal operations may be used to write to attributes marked "NO‑USER‑MODIFICATION" (although great care should be taken when doing so to ensure that you will not interfere with the normal operation of the server).
  
  

Processing internal operations in the UnboundID Server SDK is basically the same as processing external operations using the UnboundID LDAP SDK for Java. Instead of creating an external LDAP connection, it is necessary to obtain an InternalConnection object. The InternalConnection class provides most of the same methods as LDAPConnection (and implements the same LDAPInterface interface), so if you are familiar with using the LDAP SDK then you should be comfortable using this mechanism for processing internal operations in the server.

There are a few ways to obtain an InternalConnection object. If your extension is invoked during the course of processing an operation (e.g., as a plugin), then you can use the OperationContext.getInternalUserConnection method in order to obtain an internal connection authenticated as the user that requested the operation, or you can use OperationContext.getInternalRootConnection method to obtain a connection authenticated as an internal root user that will be exempt from access control restrictions. In all other cases, you can use the ServerContext.getInternalRootConnection method to obtain an internal root connection, or the ServerContext.getInternalConnection method to obtain an internal connection authenticated as any specified user.

Note that there is no need to close an internal connection when it is no longer needed because it does not consume any resources within the server. You may simply stop using an internal connection and allow it to be garbage collected when it is no longer needed.