History

Apache Directory Server has used 2 different message structures, and its architecture was foreseen to accept some new structures to hold messages. Nevertheless, having two message structures now is seen as painfull and cost time and performance, due to necessary transformation from and to those structures.

Those two structures were used in snickers and twix (those name were chosen to mimic snacc4j , which was used to check that snickers was correctly handling ASN.1 Ldap messages)

New Version 

 All the following graphics have been generated using Poseidon for UML tool. The XMI file can be downloaded here.

Message structure

In Snickers, messages are separated in two sub-classes : Request and Response. They both inherit from Message. The following diagram shows the existing relations between classes and interfaces of those three elements :

We have one more special class and interface : AbstractResultResponse and ResultResponse. Some response can have a Result object associated, some other don't. Those two elements have been added to reflect this situation.

All concrete messages will inherit from  one of these three abstract classes.

This is related to the Ldap message structure :

LDAPMessage ::= SEQUENCE {
     messageID       MessageID,
     protocolOp      CHOICE {
          ... },
     controls       [0] Controls OPTIONAL }

MessageId is an integer, protocolOp is a choice between different structures and controls is a list of controls, which are structure.

Every message received or sent to or by a ldap server will contains those elements, so it makes sense to see them at top level.

Evolution 

The message type is not necessary stored in the AbstractMessage class, All the requests and response are represented by a specific class, which inherit from Request or Response, so we know how to get their type.

We can remove the type from the AbstractMessage class.

Request messages

Here is the list of messages which implement the Request interface :

• BindRequest
• UnbindRequest
• SearchRequest
• ModifyRequest
• AddRequest
• DelRequest
• ModifyDNRequest
• CompareRequest
• AbandonRequest
• ExtendedRequest

Response messages 

Here is the list of message swhich implement the Response interface :

• BindResponse
• SearchResultEntry
• SearchResultDone
• SearchResultReference
• ModifyResponse
• AddResponse
• DelResponse
• ModifyDNResponse
• CompareResponse
• ExtendedResponse
• IntermediateResponse (RFC 4511 addition)

This responses don't send a LdapResult

A Response can contains a LdapResult element, which grammar is :

LDAPResult ::= SEQUENCE {
    resultCode         ENUMERATED {
        success                      (0),
        operationsError              (1),
        protocolError                (2),
        timeLimitExceeded            (3),
        sizeLimitExceeded            (4),
        compareFalse                 (5),
        compareTrue                  (6),
        authMethodNotSupported       (7),
        strongAuthRequired         (8),
        // strongerAuthRequired         (8), -- RFC 4511 extension
            -- 9 reserved --
        referral                     (10),
        adminLimitExceeded           (11),
        unavailableCriticalExtension (12),
        confidentialityRequired      (13),
        saslBindInProgress           (14),
        noSuchAttribute              (16),
        undefinedAttributeType       (17),
        inappropriateMatching        (18),
        constraintViolation          (19),
        attributeOrValueExists       (20),
        invalidAttributeSyntax       (21),
            -- 22-31 unused --
        noSuchObject                 (32),
        aliasProblem                 (33),
        invalidDNSyntax              (34),
            -- 35 reserved for undefined isLeaf --
        aliasDereferencingProblem    (36),
            -- 37-47 unused --
        inappropriateAuthentication  (48),
        invalidCredentials           (49),
        insufficientAccessRights     (50),
        busy                         (51),
        unavailable                  (52),
        unwillingToPerform           (53),
        loopDetect                   (54),
            -- 55-63 unused --
        namingViolation              (64),
        objectClassViolation         (65),
        notAllowedOnNonLeaf          (66),
        notAllowedOnRDN              (67),
        entryAlreadyExists           (68),
        objectClassModsProhibited    (69),
            -- 70 reserved for CLDAP --
        affectsMultipleDSAs          (71),
            -- 72-79 unused --
        other                        (80),
        ...  },
    matchedDN          LDAPDN,
    diagnosticMessage  LDAPString,
    referral           [3] Referral OPTIONAL }

Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI

URI ::= LDAPString     -- limited to characters permitted in URIs

Each resultCode will be stored in an Enum. We will create a LdapResult class to hold these data.

Message decorator

We need to extend the message to add some features :

• DSML reader and writer
• LDIF reader and writer
• ASN.1 BER reader and writer

This will be done by adding a Decorator Pattern. The idea is to add a feature without modifying the initial message, but allowing the user of this decorator to manipulate it as if it was the object itself. The following class diagram expose the implementation :