View Javadoc
1   /*
2    *  Licensed to the Apache Software Foundation (ASF) under one
3    *  or more contributor license agreements.  See the NOTICE file
4    *  distributed with this work for additional information
5    *  regarding copyright ownership.  The ASF licenses this file
6    *  to you under the Apache License, Version 2.0 (the
7    *  "License"); you may not use this file except in compliance
8    *  with the License.  You may obtain a copy of the License at
9    *  
10   *    http://www.apache.org/licenses/LICENSE-2.0
11   *  
12   *  Unless required by applicable law or agreed to in writing,
13   *  software distributed under the License is distributed on an
14   *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   *  KIND, either express or implied.  See the License for the
16   *  specific language governing permissions and limitations
17   *  under the License. 
18   *  
19   */
20  package org.apache.directory.api.ldap.model.message;
21  
22  
23  import java.util.Map;
24  
25  
26  /**
27   * Root interface for all LDAP message type interfaces.
28   * 
29   * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
30   */
31  public interface Message
32  {
33      /**
34       * Gets the LDAP message type code associated with this Message. Each
35       * request and response type has a unique message type code defined by the
36       * protocol in <a href="http://www.faqs.org/rfcs/rfc2251.html">RFC 2251</a>.
37       * 
38       * @return the message type code.
39       */
40      MessageTypeEnum getType();
41  
42  
43      /**
44       * Gets the controls associated with this message mapped by OID.
45       * 
46       * @return Map of OID strings to Control object instances.
47       */
48      Map<String, Control> getControls();
49  
50  
51      /**
52       * Gets the control associated with the given OID.
53       * 
54       * @param oid The Cntrol's OID we are looking for
55       * @return The Control object instance with the OID.
56       */
57      Control getControl( String oid );
58  
59  
60      /**
61       * Checks whether or not this message has the specified control.
62       *
63       * @param oid the OID of the control
64       * @return true if this message has the control, false if it does not
65       */
66      boolean hasControl( String oid );
67  
68  
69      /**
70       * Adds a control to this Message.
71       * 
72       * @param control the control to add.
73       * @return A Message reference
74       */
75      Message addControl( Control control );
76  
77  
78      /**
79       * Adds an array of controls to this Message.
80       * 
81       * @param controlsToAdd the controls to add.
82       * @return A Message reference
83       */
84      Message addAllControls( Control[] controlsToAdd );
85  
86  
87      /**
88       * Deletes a control removing it from this Message.
89       * 
90       * @param control the control to remove.
91       * @return A Message reference
92       */
93      Message removeControl( Control control );
94  
95  
96      /**
97       * Gets the session unique message sequence id for this message. Requests
98       * and their responses if any have the same message id. Clients at the
99       * initialization of a session start with the first message's id set to 1
100      * and increment it with each transaction.
101      * 
102      * @return the session unique message id.
103      */
104     int getMessageId();
105 
106 
107     /**
108      * Gets a message scope parameter. Message scope parameters are temporary
109      * variables associated with a message and are set locally to be used to
110      * associate housekeeping information with a request or its processing.
111      * These parameters are never transmitted nor recieved, think of them as
112      * transient data associated with the message or its processing. These
113      * transient parameters are not locked down so modifications can occur
114      * without firing LockExceptions even when this Lockable is in the locked
115      * state.
116      * 
117      * @param key the key used to access a message parameter.
118      * @return the transient message parameter value.
119      */
120     Object get( Object key );
121 
122 
123     /**
124      * Sets a message scope parameter. These transient parameters are not locked
125      * down so modifications can occur without firing LockExceptions even when
126      * this Lockable is in the locked state.
127      * 
128      * @param key the parameter key
129      * @param value the parameter value
130      * @return the old value or null
131      */
132     Object put( Object key, Object value );
133 
134 
135     /**
136      * Sets the Message ID for this request
137      * @param messageId The message Id
138      * @return A Message reference
139      */
140     Message setMessageId( int messageId );
141 }