7 - Requests and Responses (...)

We will describe all the Java structure we use for each LDAP message (Requests and Responses). This can be useful when one want to send a message or process a response, using all the possible options.

Inherited classes

All the messages inherit from a few classes that are describe here. They gather the common fields that can be used by most of the specific messages.

The Message interface

This is the mother of all the hierarchy. A message has a few characteristics that are available to all the inherited classes :

* Id : the message ID which is generated by the server or the client. You should never add it
* Controls : The list of controls you add to a request or that get added by the response

Here is the Message interface :

/**
 * Root interface for all LDAP message type interfaces.
 * 
 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
 */
public interface Message
{
    /**
     * Gets the LDAP message type code associated with this Message. Each
     * request and response type has a unique message type code defined by the
     * protocol in <a href="http://www.faqs.org/rfcs/rfc2251.html">RFC 2251</a>.
     * 
     * @return the message type code.
     */
    MessageTypeEnum getType();


    /**
     * Gets the controls associated with this message mapped by OID.
     * 
     * @return Map of OID strings to Control object instances.
     */
    Map<String, Control> getControls();


    /**
     * Gets the control associated with the given OID.
     * 
     * @param oid The Cntrol's OID we are looking for
     * @return The Control object instance with the OID.
     */
    Control getControl( String oid );


    /**
     * Checks whether or not this message has the specified control.
     *
     * @param oid the OID of the control
     * @return true if this message has the control, false if it does not
     */
    boolean hasControl( String oid );


    /**
     * Adds a control to this Message.
     * 
     * @param control the control to add.
     * @return A Message reference
     * @throws org.apache.directory.shared.ldap.model.exception.MessageException if controls cannot be added to this Message or the control is
     *             not known etc.
     */
    Message addControl( Control control ) throws MessageException;


    /**
     * Adds an array of controls to this Message.
     * 
     * @param controls the controls to add.
     * @return A Message reference
     * @throws MessageException if controls cannot be added to this Message or they are not known etc.
     */
    Message addAllControls( Control[] controls ) throws MessageException;


    /**
     * Deletes a control removing it from this Message.
     * 
     * @param control the control to remove.
     * @return A Message reference
     * @throws MessageException if controls cannot be added to this Message or the control is
     *             not known etc.
     */
    Message removeControl( Control control ) throws MessageException;


    /**
     * Gets the session unique message sequence id for this message. Requests
     * and their responses if any have the same message id. Clients at the
     * initialization of a session start with the first message's id set to 1
     * and increment it with each transaction.
     * 
     * @return the session unique message id.
     */
    int getMessageId();


    /**
     * Sets the Message ID for this request
     * @param messageId The message Id
     * @return A Message reference
     */
    Message setMessageId( int messageId );
}

Contents