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 */ 020package org.apache.directory.shared.ldap.model.message; 021 022 023import java.util.Map; 024 025import org.apache.directory.shared.ldap.model.exception.MessageException; 026 027 028/** 029 * Root interface for all LDAP message type interfaces. 030 * 031 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a> 032 */ 033public interface Message 034{ 035 /** 036 * Gets the LDAP message type code associated with this Message. Each 037 * request and response type has a unique message type code defined by the 038 * protocol in <a href="http://www.faqs.org/rfcs/rfc2251.html">RFC 2251</a>. 039 * 040 * @return the message type code. 041 */ 042 MessageTypeEnum getType(); 043 044 045 /** 046 * Gets the controls associated with this message mapped by OID. 047 * 048 * @return Map of OID strings to Control object instances. 049 */ 050 Map<String, Control> getControls(); 051 052 053 /** 054 * Gets the control associated with the given OID. 055 * 056 * @param oid The Cntrol's OID we are looking for 057 * @return The Control object instance with the OID. 058 */ 059 Control getControl( String oid ); 060 061 062 /** 063 * Checks whether or not this message has the specified control. 064 * 065 * @param oid the OID of the control 066 * @return true if this message has the control, false if it does not 067 */ 068 boolean hasControl( String oid ); 069 070 071 /** 072 * Adds a control to this Message. 073 * 074 * @param control the control to add. 075 * @return A Message reference 076 * @throws org.apache.directory.shared.ldap.model.exception.MessageException if controls cannot be added to this Message or the control is 077 * not known etc. 078 */ 079 Message addControl( Control control ) throws MessageException; 080 081 082 /** 083 * Adds an array of controls to this Message. 084 * 085 * @param controls the controls to add. 086 * @return A Message reference 087 * @throws MessageException if controls cannot be added to this Message or they are not known etc. 088 */ 089 Message addAllControls( Control[] controls ) throws MessageException; 090 091 092 /** 093 * Deletes a control removing it from this Message. 094 * 095 * @param control the control to remove. 096 * @return A Message reference 097 * @throws MessageException if controls cannot be added to this Message or the control is 098 * not known etc. 099 */ 100 Message removeControl( Control control ) throws MessageException; 101 102 103 /** 104 * Gets the session unique message sequence id for this message. Requests 105 * and their responses if any have the same message id. Clients at the 106 * initialization of a session start with the first message's id set to 1 107 * and increment it with each transaction. 108 * 109 * @return the session unique message id. 110 */ 111 int getMessageId(); 112 113 114 /** 115 * Gets a message scope parameter. Message scope parameters are temporary 116 * variables associated with a message and are set locally to be used to 117 * associate housekeeping information with a request or its processing. 118 * These parameters are never transmitted nor recieved, think of them as 119 * transient data associated with the message or its processing. These 120 * transient parameters are not locked down so modifications can occur 121 * without firing LockExceptions even when this Lockable is in the locked 122 * state. 123 * 124 * @param key the key used to access a message parameter. 125 * @return the transient message parameter value. 126 */ 127 Object get( Object key ); 128 129 130 /** 131 * Sets a message scope parameter. These transient parameters are not locked 132 * down so modifications can occur without firing LockExceptions even when 133 * this Lockable is in the locked state. 134 * 135 * @param key the parameter key 136 * @param value the parameter value 137 * @return the old value or null 138 */ 139 Object put( Object key, Object value ); 140 141 142 /** 143 * Sets the Message ID for this request 144 * @param messageId The message Id 145 * @return A Message reference 146 */ 147 Message setMessageId( int messageId ); 148}