mcs/class/Novell.Directory.Ldap/Novell.Directory.Ldap/LdapConstraints.cs

   1 /******************************************************************************
   2 * The MIT License
   3 * Copyright (c) 2003 Novell Inc.  www.novell.com
   4 *
   5 * Permission is hereby granted, free of charge, to any person obtaining  a copy
   6 * of this software and associated documentation files (the Software), to deal
   7 * in the Software without restriction, including  without limitation the rights
   8 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
   9 * copies of the Software, and to  permit persons to whom the Software is
  10 * furnished to do so, subject to the following conditions:
  11 *
  12 * The above copyright notice and this permission notice shall be included in
  13 * all copies or substantial portions of the Software.
  14 *
  15 * THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  18 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  19 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  20 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  21 * SOFTWARE.
  22 *******************************************************************************/
  23 //
  24 // Novell.Directory.Ldap.LdapConstraints.cs
  25 //
  26 // Author:
  27 //   Sunil Kumar (Sunilk@novell.com)
  28 //
  29 // (C) 2003 Novell, Inc (http://www.novell.com)
  30 //
  31
  32 using System;
  33
  34 namespace Novell.Directory.Ldap
  35 {
  36
  37         /// <summary> Defines options controlling Ldap operations on the directory.
  38         ///
  39         /// An LdapConstraints object is always associated with an LdapConnection
  40         /// object; its values can be changed with LdapConnection.setConstraints, or
  41         /// overridden by passing an LdapConstraints object to an operation.
  42         ///
  43         /// </summary>
  44         /// <seealso cref="LdapConnection.Constraints">
  45         /// </seealso>
  46         public class LdapConstraints : System.ICloneable
  47         {
  48                 /// <summary> Returns the maximum number of referrals to follow during automatic
  49                 /// referral following.  The operation will be abandoned and terminated by
  50                 /// the API with a result code of LdapException.REFERRAL_LIMIT_EXCEEDED
  51                 /// if the number of referrals in a sequence exceeds the limit.
  52                 /// It is ignored for asynchronous operations.
  53                 ///
  54                 /// </summary>
  55                 /// <returns> The maximum number of referrals to follow in sequence
  56                 ///
  57                 /// </returns>
  58                 /// <seealso cref="HopLimit">
  59                 /// </seealso>
  60                 /// <seealso cref="LdapException.REFERRAL_LIMIT_EXCEEDED">
  61                 /// </seealso>
  62                 /// <summary> Sets the maximum number of referrals to follow in sequence during
  63                 /// automatic referral following.
  64                 ///
  65                 /// </summary>
  66                 /// <param name="hop_limit">The maximum number of referrals to follow in a
  67                 /// sequence during automatic referral following.
  68                 /// The default value is 10. A value of 0 means no limit.
  69                 /// The operation will be abandoned and terminated by the
  70                 /// API with a result code of
  71                 /// LdapException.REFERRAL_LIMIT_EXCEEDED if the
  72                 /// number of referrals in a sequence exceeds the limit.
  73                 /// It is ignored for asynchronous operations.
  74                 ///
  75                 /// </param>
  76                 /// <seealso cref="LdapException.REFERRAL_LIMIT_EXCEEDED">
  77                 /// </seealso>
  78                 virtual public int HopLimit
  79                 {
  80                         get
  81                         {
  82                                 return hopLimit;
  83                         }
  84
  85                         set
  86                         {
  87                                 this.hopLimit = value;
  88                                 return ;
  89                         }
  90
  91                 }
  92                 /// <summary> Gets all the properties of the constraints object which has been
  93                 /// assigned with {@link #setProperty(String, Object)}.
  94                 /// A value of <code>null</code> is returned if no properties are defined.
  95                 ///
  96                 /// </summary>
  97                 /// <seealso cref="Object">
  98                 /// </seealso>
  99                 /// <seealso cref="LdapConnection.getProperty">
 100                 /// </seealso>
 101                 /// <summary> Sets all the properties of the constraints object.
 102                 ///
 103                 /// </summary>
 104                 /// <param name="props">the properties represented by the Hashtable object to set.
 105                 /// </param>
 106                 virtual internal System.Collections.Hashtable Properties
 107                 {
 108                         /* package */
 109
 110                         get
 111                         {
 112                                 return properties;
 113                         }
 114
 115                         /* package */
 116
 117                         set
 118                         {
 119                                 properties = (System.Collections.Hashtable) value.Clone();
 120                                 return ;
 121                         }
 122
 123                 }
 124                 /// <summary> Specified whether or not referrals are followed automatically.
 125                 ///
 126                 /// </summary>
 127                 /// <returns>  True if referrals are followed automatically, or
 128                 /// false if referrals throw an LdapReferralException.
 129                 /// </returns>
 130                 /// <summary> Specifies whether referrals are followed automatically or if
 131                 /// referrals throw an LdapReferralException.
 132                 ///
 133                 /// Referrals of any type other than to an Ldap server (for example, a
 134                 /// referral URL other than ldap://something) are ignored on automatic
 135                 /// referral following.
 136                 ///
 137                 ///  The default is false.
 138                 ///
 139                 /// </summary>
 140                 /// <param name="doReferrals">   True to follow referrals automatically.
 141                 /// False to throw an LdapReferralException if
 142                 /// the server returns a referral.
 143                 /// </param>
 144                 virtual public bool ReferralFollowing
 145                 {
 146                         get
 147                         {
 148                                 return doReferrals;
 149                         }
 150
 151                         set
 152                         {
 153                                 this.doReferrals = value;
 154                                 return ;
 155                         }
 156
 157                 }
 158                 /// <summary> Returns the maximum number of milliseconds to wait for any operation
 159                 /// under these constraints.
 160                 ///
 161                 /// If the value is 0, there is no maximum time limit on waiting
 162                 /// for operation results. The actual granularity of the timeout depends
 163                 /// platform.  This limit is enforced the the API on an
 164                 /// operation, not by the server.
 165                 /// The operation will be abandoned and terminated by the
 166                 /// API with a result code of LdapException.Ldap_TIMEOUT if the
 167                 /// operation exceeds the time limit.
 168                 ///
 169                 /// </summary>
 170                 /// <returns> The maximum number of milliseconds to wait for the operation.
 171                 ///
 172                 /// </returns>
 173                 /// <seealso cref="LdapException.Ldap_TIMEOUT">
 174                 /// </seealso>
 175                 /// <summary> Sets the maximum number of milliseconds the client waits for
 176                 /// any operation under these constraints to complete.
 177                 ///
 178                 /// If the value is 0, there is no maximum time limit enforced by the
 179                 /// API on waiting for the operation results. The actual granularity of
 180                 /// the timeout depends on the platform.
 181                 /// The operation will be abandoned and terminated by the
 182                 /// API with a result code of LdapException.Ldap_TIMEOUT if the
 183                 /// operation exceeds the time limit.
 184                 ///
 185                 /// </summary>
 186                 /// <param name="msLimit">     The maximum milliseconds to wait.
 187                 ///
 188                 /// </param>
 189                 /// <seealso cref="LdapException.Ldap_TIMEOUT">
 190                 /// </seealso>
 191                 virtual public int TimeLimit
 192                 {
 193                         get
 194                         {
 195                                 return msLimit;
 196                         }
 197
 198                         set
 199                         {
 200                                 this.msLimit = value;
 201                                 return ;
 202                         }
 203
 204                 }
 205
 206                 private int msLimit = 0;
 207                 private int hopLimit = 10;
 208                 private bool doReferrals = false;
 209                 private LdapReferralHandler refHandler = null;
 210                 private LdapControl[] controls = null;
 211                 private static System.Object nameLock; // protect agentNum
 212                 private static int lConsNum = 0; // Debug, LdapConstraints num
 213                 private System.String name; // String name for debug
 214                 private System.Collections.Hashtable properties = null; // Properties
 215
 216                 /// <summary> Constructs a new LdapConstraints object that specifies the default
 217                 /// set of constraints.
 218                 /// </summary>
 219                 public LdapConstraints()
 220                 {
 221                         // Get a unique constraints name for debug
 222                         return ;
 223                 }
 224
 225                 /// <summary> Constructs a new LdapConstraints object specifying constraints that
 226                 /// control wait time, and referral handling.
 227                 ///
 228                 /// </summary>
 229                 /// <param name="msLimit"> The maximum time in milliseconds to wait for results.
 230                 /// The default is 0, which means that there is no
 231                 /// maximum time limit. This limit is enforced for an
 232                 /// operation by the API, not by the server.
 233                 /// The operation will be abandoned and terminated by the
 234                 /// API with a result code of LdapException.Ldap_TIMEOUT
 235                 /// if the operation exceeds the time limit.
 236                 ///
 237                 /// </param>
 238                 /// <param name="doReferrals">Determines whether to automatically follow
 239                 /// referrals or not. Specify true to follow
 240                 /// referrals automatically, and false to throw
 241                 /// an LdapReferralException if the server responds
 242                 /// with a referral. False is the default value.
 243                 /// The way referrals are followed automatically is
 244                 /// determined by the setting of the handler parameter.
 245                 /// It is ignored for asynchronous operations.
 246                 ///
 247                 /// </param>
 248                 /// <param name="handler">  The custom authentication handler called when
 249                 /// LdapConnection needs to authenticate, typically on
 250                 /// following a referral.  A null may be specified to
 251                 /// indicate default authentication processing, i.e.
 252                 /// referrals are followed with anonymous authentication.
 253                 /// The handler object may be an implemention of either the
 254                 /// LdapBindHandler or LdapAuthHandler interface.
 255                 /// The implementation of these interfaces determines how
 256                 /// authentication is performed when following referrals.
 257                 /// It is ignored for asynchronous operations.
 258                 ///
 259                 /// </param>
 260                 /// <param name="hop_limit">The maximum number of referrals to follow in a
 261                 /// sequence during automatic referral following.
 262                 /// The default value is 10. A value of 0 means no limit.
 263                 /// The operation will be abandoned and terminated by the
 264                 /// API with a result code of
 265                 /// LdapException.REFERRAL_LIMIT_EXCEEDED if the
 266                 /// number of referrals in a sequence exceeds the limit.
 267                 /// It is ignored for asynchronous operations.
 268                 ///
 269                 /// </param>
 270                 /// <seealso cref="LdapException.Ldap_TIMEOUT">
 271                 /// </seealso>
 272                 /// <seealso cref="LdapException.REFERRAL_LIMIT_EXCEEDED">
 273                 /// </seealso>
 274                 /// <seealso cref="LdapException.REFERRAL">
 275                 /// </seealso>
 276                 /// <seealso cref="LdapReferralException">
 277                 /// </seealso>
 278                 /// <seealso cref="LdapBindHandler">
 279                 /// </seealso>
 280                 /// <seealso cref="LdapAuthHandler">
 281                 /// </seealso>
 282                 public LdapConstraints(int msLimit, bool doReferrals, LdapReferralHandler handler, int hop_limit)
 283                 {
 284                         this.msLimit = msLimit;
 285                         this.doReferrals = doReferrals;
 286                         this.refHandler = handler;
 287                         this.hopLimit = hop_limit;
 288                         // Get a unique constraints name for debug
 289                         return ;
 290                 }
 291
 292                 /// <summary> Returns the controls to be sent to the server.
 293                 ///
 294                 /// </summary>
 295                 /// <returns> The controls to be sent to the server, or null if none.
 296                 ///
 297                 /// </returns>
 298                 /// <seealso cref="Controls">
 299                 /// </seealso>
 300                 public virtual LdapControl[] getControls()
 301                 {
 302                         return controls;
 303                 }
 304
 305                 /// <summary> Gets a property of the constraints object which has been
 306                 /// assigned with {@link #setProperty(String, Object)}.
 307                 ///
 308                 /// </summary>
 309                 /// <param name="name">  Name of the property to be returned.
 310                 ///
 311                 /// </param>
 312                 /// <returns> the object associated with the property,
 313                 /// or <code>null</code> if the property is not set.
 314                 ///
 315                 /// </returns>
 316                 /// <seealso cref="Object">
 317                 /// </seealso>
 318                 /// <seealso cref="LdapConnection.getProperty(String)">
 319                 /// </seealso>
 320                 public virtual System.Object getProperty(System.String name)
 321                 {
 322                         if (properties == null)
 323                         {
 324                                 return null; // Requested property not available.
 325                         }
 326                         return properties[name];
 327                 }
 328
 329                 /// <summary> Returns an object that can process authentication for automatic
 330                 /// referral handling.
 331                 ///
 332                 /// It may be null.
 333                 ///
 334                 /// </summary>
 335                 /// <returns> An LdapReferralHandler object that can process authentication.
 336                 /// </returns>
 337                 /*package*/
 338                 internal virtual LdapReferralHandler getReferralHandler()
 339                 {
 340                         return refHandler;
 341                 }
 342
 343                 /// <summary> Sets a single control to be sent to the server.
 344                 ///
 345                 /// </summary>
 346                 /// <param name="control">    A single control to be sent to the server or
 347                 /// null if none.
 348                 /// </param>
 349                 public virtual void  setControls(LdapControl control)
 350                 {
 351                         if (control == null)
 352                         {
 353                                 this.controls = null;
 354                                 return ;
 355                         }
 356                         this.controls = new LdapControl[1];
 357                         this.controls[0] = (LdapControl) control.Clone();
 358                         return ;
 359                 }
 360
 361                 /// <summary> Sets controls to be sent to the server.
 362                 ///
 363                 /// </summary>
 364                 /// <param name="controls">     An array of controls to be sent to the server or
 365                 /// null if none.
 366                 /// </param>
 367                 public virtual void  setControls(LdapControl[] controls)
 368                 {
 369                         if ((controls == null) || (controls.Length == 0))
 370                         {
 371                                 this.controls = null;
 372                                 return ;
 373                         }
 374                         this.controls = new LdapControl[controls.Length];
 375                         for (int i = 0; i < controls.Length; i++)
 376                         {
 377                                 this.controls[i] = (LdapControl) controls[i].Clone();
 378                         }
 379                         return ;
 380                 }
 381
 382                 /// <summary> Sets a property of the constraints object.
 383                 ///
 384                 /// No property names have been defined at this time, but the
 385                 /// mechanism is in place in order to support revisional as well as
 386                 /// dynamic and proprietary extensions to operation modifiers.
 387                 ///
 388                 /// </summary>
 389                 /// <param name="name">   Name of the property to set.
 390                 ///
 391                 /// </param>
 392                 /// <param name="value">  Value to assign to the property.
 393                 /// property is not supported.
 394                 ///
 395                 /// @throws NullPointerException if name or value are null
 396                 ///
 397                 /// </param>
 398                 /// <seealso cref="LdapConnection.getProperty">
 399                 /// </seealso>
 400                 public virtual void  setProperty(System.String name, System.Object value_Renamed)
 401                 {
 402                         if (properties == null)
 403                         {
 404                                 properties = new System.Collections.Hashtable();
 405                         }
 406                         SupportClass.PutElement(properties, name, value_Renamed);
 407                         return ;
 408                 }
 409
 410                 /// <summary> Specifies the object that will process authentication requests
 411                 /// during automatic referral following.
 412                 ///
 413                 /// The default is null.
 414                 ///
 415                 /// </summary>
 416                 /// <param name="handler">   An object that implements LdapBindHandler or
 417                 /// LdapAuthHandler
 418                 ///
 419                 /// </param>
 420                 /// <seealso cref="LdapAuthHandler">
 421                 /// </seealso>
 422                 /// <seealso cref="LdapBindHandler">
 423                 /// </seealso>
 424                 public virtual void  setReferralHandler(LdapReferralHandler handler)
 425                 {
 426                         refHandler = handler;
 427                         return ;
 428                 }
 429
 430                 /// <summary> Clones an LdapConstraints object.
 431                 ///
 432                 /// </summary>
 433                 /// <returns> An LdapConstraints object.
 434                 /// </returns>
 435                 public System.Object Clone()
 436                 {
 437                         try
 438                         {
 439                                 System.Object newObj = base.MemberwiseClone();
 440                                 if (controls != null)
 441                                 {
 442                                         ((LdapConstraints) newObj).controls = new LdapControl[controls.Length];
 443                                         controls.CopyTo(((LdapConstraints) newObj).controls, 0);
 444                                 }
 445                                 if (properties != null)
 446                                 {
 447                                         ((LdapConstraints) newObj).properties = (System.Collections.Hashtable) properties.Clone();
 448                                 }
 449                                 return newObj;
 450                         }
 451                         catch (System.Exception ce)
 452                         {
 453                                 throw new System.SystemException("Internal error, cannot create clone");
 454                         }
 455                 }
 456                 static LdapConstraints()
 457                 {
 458                         nameLock = new System.Object();
 459                 }
 460         }
 461 }