001    /*
002     *  Licensed to the Apache Software Foundation (ASF) under one
003     *  or more contributor license agreements.  See the NOTICE file
004     *  distributed with this work for additional information
005     *  regarding copyright ownership.  The ASF licenses this file
006     *  to you under the Apache License, Version 2.0 (the
007     *  "License"); you may not use this file except in compliance
008     *  with the License.  You may obtain a copy of the License at
009     *  
010     *    http://www.apache.org/licenses/LICENSE-2.0
011     *  
012     *  Unless required by applicable law or agreed to in writing,
013     *  software distributed under the License is distributed on an
014     *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     *  KIND, either express or implied.  See the License for the
016     *  specific language governing permissions and limitations
017     *  under the License. 
018     *  
019     */
020    package org.apache.directory.shared.ldap.message.internal;
021    
022    
023    import java.util.Map;
024    
025    import org.apache.directory.shared.ldap.codec.MessageTypeEnum;
026    import org.apache.directory.shared.ldap.codec.controls.CodecControl;
027    import org.apache.directory.shared.ldap.message.MessageException;
028    import org.apache.directory.shared.ldap.message.control.Control;
029    
030    
031    /**
032     * Root interface for all LDAP message type interfaces.
033     * 
034     * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
035     * @version $Rev: 910150 $
036     */
037    public interface InternalMessage
038    {
039        /**
040         * Gets the LDAP message type code associated with this Message. Each
041         * request and response type has a unique message type code defined by the
042         * protocol in <a href="http://www.faqs.org/rfcs/rfc2251.html">RFC 2251</a>.
043         * 
044         * @return the message type code.
045         */
046        MessageTypeEnum getType();
047    
048    
049        /**
050         * Gets the controls associated with this message mapped by OID.
051         * 
052         * @return Map of OID strings to Control object instances.
053         * @see CodecControl
054         */
055        Map<String, Control> getControls();
056    
057        
058        /**
059         * Checks whether or not this message has the specified control.
060         *
061         * @param oid the OID of the control
062         * @return true if this message has the control, false if it does not
063         */
064        boolean hasControl( String oid );
065        
066    
067        /**
068         * Adds a control to this Message.
069         * 
070         * @param control
071         *            the control to add.
072         * @throws MessageException
073         *             if controls cannot be added to this Message or the control is
074         *             not known etc.
075         */
076        void add( Control control ) throws MessageException;
077    
078    
079        /**
080         * Adds an array of controls to this Message.
081         * 
082         * @param controls the controls to add.
083         * @throws MessageException if controls cannot be added to this Message or they are not known etc.
084         */
085        void addAll( Control[] controls ) throws MessageException;
086    
087    
088        /**
089         * Deletes a control removing it from this Message.
090         * 
091         * @param control
092         *            the control to remove.
093         * @throws MessageException
094         *             if controls cannot be added to this Message or the control is
095         *             not known etc.
096         */
097        void remove( Control control ) throws MessageException;
098    
099    
100        /**
101         * Gets the session unique message sequence id for this message. Requests
102         * and their responses if any have the same message id. Clients at the
103         * initialization of a session start with the first message's id set to 1
104         * and increment it with each transaction.
105         * 
106         * @return the session unique message id.
107         */
108        int getMessageId();
109    
110    
111        /**
112         * Gets a message scope parameter. Message scope parameters are temporary
113         * variables associated with a message and are set locally to be used to
114         * associate housekeeping information with a request or its processing.
115         * These parameters are never transmitted nor recieved, think of them as
116         * transient data associated with the message or its processing. These
117         * transient parameters are not locked down so modifications can occur
118         * without firing LockExceptions even when this Lockable is in the locked
119         * state.
120         * 
121         * @param key
122         *            the key used to access a message parameter.
123         * @return the transient message parameter value.
124         */
125        Object get( Object key );
126    
127    
128        /**
129         * Sets a message scope parameter. These transient parameters are not locked
130         * down so modifications can occur without firing LockExceptions even when
131         * this Lockable is in the locked state.
132         * 
133         * @param key
134         *            the parameter key
135         * @param value
136         *            the parameter value
137         * @return the old value or null
138         */
139        Object put( Object key, Object value );
140    }