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.api.ldap.model.message; 021 022 023import java.util.Map; 024 025 026/** 027 * Root interface for all LDAP message type interfaces. 028 * 029 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a> 030 */ 031public interface Message 032{ 033 /** 034 * Gets the LDAP message type code associated with this Message. Each 035 * request and response type has a unique message type code defined by the 036 * protocol in <a href="http://www.faqs.org/rfcs/rfc2251.html">RFC 2251</a>. 037 * 038 * @return the message type code. 039 */ 040 MessageTypeEnum getType(); 041 042 043 /** 044 * Gets the controls associated with this message mapped by OID. 045 * 046 * @return Map of OID strings to Control object instances. 047 */ 048 Map<String, Control> getControls(); 049 050 051 /** 052 * Gets the control associated with the given OID. 053 * 054 * @param oid The Cntrol's OID we are looking for 055 * @return The Control object instance with the OID. 056 */ 057 Control getControl( String oid ); 058 059 060 /** 061 * Checks whether or not this message has the specified control. 062 * 063 * @param oid the OID of the control 064 * @return true if this message has the control, false if it does not 065 */ 066 boolean hasControl( String oid ); 067 068 069 /** 070 * Adds a control to this Message. 071 * 072 * @param control the control to add. 073 * @return A Message reference 074 */ 075 Message addControl( Control control ); 076 077 078 /** 079 * Adds an array of controls to this Message. 080 * 081 * @param controlsToAdd the controls to add. 082 * @return A Message reference 083 */ 084 Message addAllControls( Control[] controlsToAdd ); 085 086 087 /** 088 * Deletes a control removing it from this Message. 089 * 090 * @param control the control to remove. 091 * @return A Message reference 092 */ 093 Message removeControl( Control control ); 094 095 096 /** 097 * Gets the session unique message sequence id for this message. Requests 098 * and their responses if any have the same message id. Clients at the 099 * 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}