001 /* 002 * CDDL HEADER START 003 * 004 * The contents of this file are subject to the terms of the 005 * Common Development and Distribution License, Version 1.0 only 006 * (the "License"). You may not use this file except in compliance 007 * with the License. 008 * 009 * You can obtain a copy of the license at 010 * trunk/opends/resource/legal-notices/OpenDS.LICENSE 011 * or https://OpenDS.dev.java.net/OpenDS.LICENSE. 012 * See the License for the specific language governing permissions 013 * and limitations under the License. 014 * 015 * When distributing Covered Code, include this CDDL HEADER in each 016 * file and include the License file at 017 * trunk/opends/resource/legal-notices/OpenDS.LICENSE. If applicable, 018 * add the following below this CDDL HEADER, with the fields enclosed 019 * by brackets "[]" replaced with your own identifying information: 020 * Portions Copyright [yyyy] [name of copyright owner] 021 * 022 * CDDL HEADER END 023 * 024 * 025 * Copyright 2007-2008 Sun Microsystems, Inc. 026 */ 027 028 package org.opends.server.admin.client; 029 030 031 032 import java.util.Collection; 033 import java.util.SortedSet; 034 035 import org.opends.server.admin.AbstractManagedObjectDefinition; 036 import org.opends.server.admin.Configuration; 037 import org.opends.server.admin.DefaultBehaviorException; 038 import org.opends.server.admin.DefinitionDecodingException; 039 import org.opends.server.admin.IllegalPropertyValueException; 040 import org.opends.server.admin.InstantiableRelationDefinition; 041 import org.opends.server.admin.ManagedObjectAlreadyExistsException; 042 import org.opends.server.admin.ManagedObjectDefinition; 043 import org.opends.server.admin.ConfigurationClient; 044 import org.opends.server.admin.ManagedObjectNotFoundException; 045 import org.opends.server.admin.ManagedObjectPath; 046 import org.opends.server.admin.OptionalRelationDefinition; 047 import org.opends.server.admin.PropertyDefinition; 048 import org.opends.server.admin.PropertyIsMandatoryException; 049 import org.opends.server.admin.PropertyIsReadOnlyException; 050 import org.opends.server.admin.PropertyIsSingleValuedException; 051 import org.opends.server.admin.PropertyProvider; 052 import org.opends.server.admin.SingletonRelationDefinition; 053 054 055 056 /** 057 * A generic interface for accessing client-side managed objects. 058 * <p> 059 * A managed object comprises of zero or more properties. A property 060 * has associated with it three sets of property value(s). These are: 061 * <ul> 062 * <li><i>default value(s)</i> - these value(s) represent the 063 * default behavior for the property when it has no active values. 064 * When a property inherits its default value(s) from elsewhere (i.e. 065 * a property in another managed object), the default value(s) 066 * represent the active value(s) of the inherited property at the time 067 * the managed object was retrieved 068 * <li><i>active value(s)</i> - these value(s) represent the state 069 * of the property at the time the managed object was retrieved 070 * <li><i>pending value(s)</i> - these value(s) represent any 071 * modifications made to the property's value(s) since the managed 072 * object object was retrieved and before the changes have been 073 * committed using the {@link #commit()} method, the pending values 074 * can be empty indicating that the property should be modified back 075 * to its default values. 076 * </ul> 077 * In addition, a property has an <i>effective state</i> defined by 078 * its <i>effective values</i> which are derived by evaluating the 079 * following rules in the order presented: 080 * <ul> 081 * <li>the <i>pending values</i> if defined and non-empty 082 * <li>or, the <i>default values</i> if the pending values are 083 * defined but are empty 084 * <li>or, the <i>active values</i> if defined and non-empty 085 * <li>or, the <i>default values</i> if there are no active values 086 * <li>or, an empty set of values, if there are no default values. 087 * </ul> 088 * 089 * @param <T> 090 * The type of client configuration represented by the client 091 * managed object. 092 */ 093 public interface ManagedObject<T extends ConfigurationClient> extends 094 PropertyProvider { 095 096 /** 097 * Adds this managed object to the server or commits any changes 098 * made to it depending on whether or not the managed object already 099 * exists on the server. Pending property values will be committed 100 * to the managed object. If successful, the pending values will 101 * become active values. 102 * <p> 103 * See the class description for more information regarding pending 104 * and active values. 105 * 106 * @throws ManagedObjectAlreadyExistsException 107 * If the managed object cannot be added to the server 108 * because it already exists. 109 * @throws MissingMandatoryPropertiesException 110 * If the managed object contains some mandatory 111 * properties which have been left undefined. 112 * @throws ConcurrentModificationException 113 * If the managed object is being added to the server but 114 * its parent has been removed by another client, or if 115 * this managed object is being modified but it has been 116 * removed from the server by another client. 117 * @throws OperationRejectedException 118 * If this managed object cannot be added or modified due 119 * to some client-side or server-side constraint which 120 * cannot be satisfied. 121 * @throws AuthorizationException 122 * If the server refuses to add or modify this managed 123 * object because the client does not have the correct 124 * privileges. 125 * @throws CommunicationException 126 * If the client cannot contact the server due to an 127 * underlying communication problem. 128 */ 129 void commit() throws ManagedObjectAlreadyExistsException, 130 MissingMandatoryPropertiesException, ConcurrentModificationException, 131 OperationRejectedException, AuthorizationException, 132 CommunicationException; 133 134 135 /** 136 * Determines whether or not this managed object has been modified since it 137 * was constructed. 138 * In other words, whether or not the set of pending values differs from 139 * the set of active values. 140 * 141 * @return Returns <code>true</code> if this managed object has been 142 * modified since it was constructed. 143 */ 144 boolean isModified(); 145 146 147 /** 148 * Creates a new child managed object bound to the specified 149 * instantiable relation. The new managed object will initially not 150 * contain any property values (including mandatory properties). 151 * Once the managed object has been configured it can be added to 152 * the server using the {@link #commit()} method. 153 * 154 * @param <C> 155 * The expected type of the child managed object 156 * configuration client. 157 * @param <S> 158 * The expected type of the child managed object 159 * server configuration. 160 * @param <CC> 161 * The actual type of the added managed object 162 * configuration client. 163 * @param r 164 * The instantiable relation definition. 165 * @param d 166 * The definition of the managed object to be created. 167 * @param name 168 * The name of the child managed object. 169 * @param exceptions 170 * A collection in which to place any 171 * {@link DefaultBehaviorException}s that occurred whilst 172 * attempting to determine the managed object's default 173 * values. 174 * @return Returns a new child managed object bound to the specified 175 * instantiable relation. 176 * @throws IllegalManagedObjectNameException 177 * If the name of the child managed object is invalid. 178 * @throws IllegalArgumentException 179 * If the relation definition is not associated with this 180 * managed object's definition. 181 */ 182 <C extends ConfigurationClient, S extends Configuration, CC extends C> 183 ManagedObject<CC> createChild(InstantiableRelationDefinition<C, S> r, 184 ManagedObjectDefinition<CC, ? extends S> d, String name, 185 Collection<DefaultBehaviorException> exceptions) 186 throws IllegalManagedObjectNameException, IllegalArgumentException; 187 188 189 190 /** 191 * Creates a new child managed object bound to the specified 192 * optional relation. The new managed object will initially not 193 * contain any property values (including mandatory properties). 194 * Once the managed object has been configured it can be added to 195 * the server using the {@link #commit()} method. 196 * 197 * @param <C> 198 * The expected type of the child managed object 199 * configuration client. 200 * @param <S> 201 * The expected type of the child managed object 202 * server configuration. 203 * @param <CC> 204 * The actual type of the added managed object 205 * configuration client. 206 * @param r 207 * The optional relation definition. 208 * @param d 209 * The definition of the managed object to be created. 210 * @param exceptions 211 * A collection in which to place any 212 * {@link DefaultBehaviorException}s that occurred whilst 213 * attempting to determine the managed object's default 214 * values. 215 * @return Returns a new child managed object bound to the specified 216 * optional relation. 217 * @throws IllegalArgumentException 218 * If the relation definition is not associated with this 219 * managed object's definition. 220 */ 221 <C extends ConfigurationClient, S extends Configuration, CC extends C> 222 ManagedObject<CC> createChild(OptionalRelationDefinition<C, S> r, 223 ManagedObjectDefinition<CC, ? extends S> d, 224 Collection<DefaultBehaviorException> exceptions) 225 throws IllegalArgumentException; 226 227 228 229 /** 230 * Retrieves an instantiable child managed object. 231 * 232 * @param <C> 233 * The requested type of the child managed object 234 * configuration client. 235 * @param <S> 236 * The type of server managed object configuration that the 237 * relation definition refers to. 238 * @param r 239 * The instantiable relation definition. 240 * @param name 241 * The name of the child managed object. 242 * @return Returns the instantiable child managed object. 243 * @throws IllegalArgumentException 244 * If the relation definition is not associated with this 245 * managed object's definition. 246 * @throws DefinitionDecodingException 247 * If the managed object was found but its type could not 248 * be determined. 249 * @throws ManagedObjectDecodingException 250 * If the managed object was found but one or more of its 251 * properties could not be decoded. 252 * @throws ManagedObjectNotFoundException 253 * If the requested managed object could not be found on 254 * the server. 255 * @throws ConcurrentModificationException 256 * If this managed object has been removed from the server 257 * by another client. 258 * @throws AuthorizationException 259 * If the server refuses to retrieve the managed object 260 * because the client does not have the correct 261 * privileges. 262 * @throws CommunicationException 263 * If the client cannot contact the server due to an 264 * underlying communication problem. 265 */ 266 <C extends ConfigurationClient, S extends Configuration> 267 ManagedObject<? extends C> getChild(InstantiableRelationDefinition<C, S> r, 268 String name) throws IllegalArgumentException, DefinitionDecodingException, 269 ManagedObjectDecodingException, ManagedObjectNotFoundException, 270 ConcurrentModificationException, AuthorizationException, 271 CommunicationException; 272 273 274 275 /** 276 * Retrieves an optional child managed object. 277 * 278 * @param <C> 279 * The requested type of the child managed object 280 * configuration client. 281 * @param <S> 282 * The type of server managed object configuration that the 283 * relation definition refers to. 284 * @param r 285 * The optional relation definition. 286 * @return Returns the optional child managed object. 287 * @throws IllegalArgumentException 288 * If the relation definition is not associated with this 289 * managed object's definition. 290 * @throws DefinitionDecodingException 291 * If the managed object was found but its type could not 292 * be determined. 293 * @throws ManagedObjectDecodingException 294 * If the managed object was found but one or more of its 295 * properties could not be decoded. 296 * @throws ManagedObjectNotFoundException 297 * If the requested managed object could not be found on 298 * the server. 299 * @throws ConcurrentModificationException 300 * If this managed object has been removed from the server 301 * by another client. 302 * @throws AuthorizationException 303 * If the server refuses to retrieve the managed object 304 * because the client does not have the correct 305 * privileges. 306 * @throws CommunicationException 307 * If the client cannot contact the server due to an 308 * underlying communication problem. 309 */ 310 <C extends ConfigurationClient, S extends Configuration> 311 ManagedObject<? extends C> getChild(OptionalRelationDefinition<C, S> r) 312 throws IllegalArgumentException, DefinitionDecodingException, 313 ManagedObjectDecodingException, ManagedObjectNotFoundException, 314 ConcurrentModificationException, AuthorizationException, 315 CommunicationException; 316 317 318 319 /** 320 * Retrieves a singleton child managed object. 321 * 322 * @param <C> 323 * The requested type of the child managed object 324 * configuration client. 325 * @param <S> 326 * The type of server managed object configuration that the 327 * relation definition refers to. 328 * @param r 329 * The singleton relation definition. 330 * @return Returns the singleton child managed object. 331 * @throws IllegalArgumentException 332 * If the relation definition is not associated with this 333 * managed object's definition. 334 * @throws DefinitionDecodingException 335 * If the managed object was found but its type could not 336 * be determined. 337 * @throws ManagedObjectDecodingException 338 * If the managed object was found but one or more of its 339 * properties could not be decoded. 340 * @throws ManagedObjectNotFoundException 341 * If the requested managed object could not be found on 342 * the server. 343 * @throws ConcurrentModificationException 344 * If this managed object has been removed from the server 345 * by another client. 346 * @throws AuthorizationException 347 * If the server refuses to retrieve the managed object 348 * because the client does not have the correct 349 * privileges. 350 * @throws CommunicationException 351 * If the client cannot contact the server due to an 352 * underlying communication problem. 353 */ 354 <C extends ConfigurationClient, S extends Configuration> 355 ManagedObject<? extends C> getChild(SingletonRelationDefinition<C, S> r) 356 throws IllegalArgumentException, DefinitionDecodingException, 357 ManagedObjectDecodingException, ManagedObjectNotFoundException, 358 ConcurrentModificationException, AuthorizationException, 359 CommunicationException; 360 361 362 363 /** 364 * Creates a client configuration view of this managed object. 365 * Modifications made to this managed object will be reflected in 366 * the client configuration view and vice versa. 367 * 368 * @return Returns a client configuration view of this managed 369 * object. 370 */ 371 T getConfiguration(); 372 373 374 375 /** 376 * Gets the definition associated with this managed object. 377 * 378 * @return Returns the definition associated with this managed 379 * object. 380 */ 381 ManagedObjectDefinition<T, ? extends Configuration> 382 getManagedObjectDefinition(); 383 384 385 386 /** 387 * Gets the path of this managed object. 388 * 389 * @return Returns the path of this managed object. 390 */ 391 ManagedObjectPath<T, ? extends Configuration> getManagedObjectPath(); 392 393 394 395 /** 396 * Gets a mutable copy of the set of default values for the 397 * specified property. 398 * 399 * @param <PD> 400 * The type of the property to be retrieved. 401 * @param pd 402 * The property to be retrieved. 403 * @return Returns the property's default values, or an empty set if 404 * there are no default values defined. 405 * @throws IllegalArgumentException 406 * If the property definition is not associated with this 407 * managed object's definition. 408 */ 409 <PD> SortedSet<PD> getPropertyDefaultValues(PropertyDefinition<PD> pd) 410 throws IllegalArgumentException; 411 412 413 414 /** 415 * Gets the effective value of the specified property. 416 * <p> 417 * See the class description for more information about how the 418 * effective property value is derived. 419 * 420 * @param <PD> 421 * The type of the property to be retrieved. 422 * @param pd 423 * The property to be retrieved. 424 * @return Returns the property's effective value, or 425 * <code>null</code> if there is no effective value 426 * defined. 427 * @throws IllegalArgumentException 428 * If the property definition is not associated with this 429 * managed object's definition. 430 */ 431 <PD> PD getPropertyValue(PropertyDefinition<PD> pd) 432 throws IllegalArgumentException; 433 434 435 436 /** 437 * Gets a mutable copy of the set of effective values for the 438 * specified property. 439 * <p> 440 * See the class description for more information about how the 441 * effective property values are derived. 442 * 443 * @param <PD> 444 * The type of the property to be retrieved. 445 * @param pd 446 * The property to be retrieved. 447 * @return Returns the property's effective values, or an empty set 448 * if there are no effective values defined. 449 * @throws IllegalArgumentException 450 * If the property definition is not associated with this 451 * managed object's definition. 452 */ 453 <PD> SortedSet<PD> getPropertyValues(PropertyDefinition<PD> pd) 454 throws IllegalArgumentException; 455 456 457 458 /** 459 * Determines whether or not the specified property is set. If the 460 * property is unset, then any default behavior associated with the 461 * property applies. 462 * 463 * @param pd 464 * The property definition. 465 * @return Returns <code>true</code> if the property has been set, 466 * or <code>false</code> if it is unset and any default 467 * behavior associated with the property applies. 468 * @throws IllegalArgumentException 469 * If the property definition is not associated with this 470 * managed object's definition. 471 */ 472 boolean isPropertyPresent(PropertyDefinition<?> pd) 473 throws IllegalArgumentException; 474 475 476 477 /** 478 * Determines whether or not the optional managed object associated 479 * with the specified optional relations exists. 480 * 481 * @param <C> 482 * The type of client managed object configuration that the 483 * relation definition refers to. 484 * @param <S> 485 * The type of server managed object configuration that the 486 * relation definition refers to. 487 * @param r 488 * The optional relation definition. 489 * @return Returns <code>true</code> if the optional managed 490 * object exists, <code>false</code> otherwise. 491 * @throws IllegalArgumentException 492 * If the relation definition is not associated with this 493 * managed object's definition. 494 * @throws ConcurrentModificationException 495 * If this managed object has been removed from the server 496 * by another client. 497 * @throws AuthorizationException 498 * If the server refuses to make the determination because 499 * the client does not have the correct privileges. 500 * @throws CommunicationException 501 * If the client cannot contact the server due to an 502 * underlying communication problem. 503 */ 504 <C extends ConfigurationClient, S extends Configuration> 505 boolean hasChild(OptionalRelationDefinition<C, S> r) 506 throws IllegalArgumentException, ConcurrentModificationException, 507 AuthorizationException, CommunicationException; 508 509 510 511 /** 512 * Lists the child managed objects associated with the specified 513 * instantiable relation. 514 * 515 * @param <C> 516 * The type of client managed object configuration that the 517 * relation definition refers to. 518 * @param <S> 519 * The type of server managed object configuration that the 520 * relation definition refers to. 521 * @param r 522 * The instantiable relation definition. 523 * @return Returns the names of the child managed objects. 524 * @throws IllegalArgumentException 525 * If the relation definition is not associated with this 526 * managed object's definition. 527 * @throws ConcurrentModificationException 528 * If this managed object has been removed from the server 529 * by another client. 530 * @throws AuthorizationException 531 * If the server refuses to list the managed objects 532 * because the client does not have the correct 533 * privileges. 534 * @throws CommunicationException 535 * If the client cannot contact the server due to an 536 * underlying communication problem. 537 */ 538 <C extends ConfigurationClient, S extends Configuration> 539 String[] listChildren(InstantiableRelationDefinition<C, S> r) 540 throws IllegalArgumentException, ConcurrentModificationException, 541 AuthorizationException, CommunicationException; 542 543 544 545 /** 546 * Lists the child managed objects associated with the specified 547 * instantiable relation which are a sub-type of the specified 548 * managed object definition. 549 * 550 * @param <C> 551 * The type of client managed object configuration that the 552 * relation definition refers to. 553 * @param <S> 554 * The type of server managed object configuration that the 555 * relation definition refers to. 556 * @param r 557 * The instantiable relation definition. 558 * @param d 559 * The managed object definition. 560 * @return Returns the names of the child managed objects which are 561 * a sub-type of the specified managed object definition. 562 * @throws IllegalArgumentException 563 * If the relation definition is not associated with this 564 * managed object's definition. 565 * @throws ConcurrentModificationException 566 * If this managed object has been removed from the server 567 * by another client. 568 * @throws AuthorizationException 569 * If the server refuses to list the managed objects 570 * because the client does not have the correct 571 * privileges. 572 * @throws CommunicationException 573 * If the client cannot contact the server due to an 574 * underlying communication problem. 575 */ 576 <C extends ConfigurationClient, S extends Configuration> 577 String[] listChildren(InstantiableRelationDefinition<C, S> r, 578 AbstractManagedObjectDefinition<? extends C, ? extends S> d) 579 throws IllegalArgumentException, ConcurrentModificationException, 580 AuthorizationException, CommunicationException; 581 582 583 584 /** 585 * Removes the named instantiable child managed object. 586 * 587 * @param <C> 588 * The type of client managed object configuration that the 589 * relation definition refers to. 590 * @param <S> 591 * The type of server managed object configuration that the 592 * relation definition refers to. 593 * @param r 594 * The instantiable relation definition. 595 * @param name 596 * The name of the child managed object to be removed. 597 * @throws IllegalArgumentException 598 * If the relation definition is not associated with this 599 * managed object's definition. 600 * @throws ManagedObjectNotFoundException 601 * If the managed object could not be removed because it 602 * could not found on the server. 603 * @throws OperationRejectedException 604 * If the managed object cannot be removed due to some 605 * client-side or server-side constraint which cannot be 606 * satisfied (for example, if it is referenced by another 607 * managed object). 608 * @throws ConcurrentModificationException 609 * If this managed object has been removed from the server 610 * by another client. 611 * @throws AuthorizationException 612 * If the server refuses to remove the managed objects 613 * because the client does not have the correct 614 * privileges. 615 * @throws CommunicationException 616 * If the client cannot contact the server due to an 617 * underlying communication problem. 618 */ 619 <C extends ConfigurationClient, S extends Configuration> 620 void removeChild(InstantiableRelationDefinition<C, S> r, String name) 621 throws IllegalArgumentException, ManagedObjectNotFoundException, 622 OperationRejectedException, ConcurrentModificationException, 623 AuthorizationException, CommunicationException; 624 625 626 627 /** 628 * Removes an optional child managed object. 629 * 630 * @param <C> 631 * The type of client managed object configuration that the 632 * relation definition refers to. 633 * @param <S> 634 * The type of server managed object configuration that the 635 * relation definition refers to. 636 * @param r 637 * The optional relation definition. 638 * @throws IllegalArgumentException 639 * If the relation definition is not associated with this 640 * managed object's definition. 641 * @throws ManagedObjectNotFoundException 642 * If the managed object could not be removed because it 643 * could not found on the server. 644 * @throws OperationRejectedException 645 * If the managed object cannot be removed due to some 646 * client-side or server-side constraint which cannot be 647 * satisfied (for example, if it is referenced by another 648 * managed object). 649 * @throws ConcurrentModificationException 650 * If this managed object has been removed from the server 651 * by another client. 652 * @throws AuthorizationException 653 * If the server refuses to remove the managed objects 654 * because the client does not have the correct 655 * privileges. 656 * @throws CommunicationException 657 * If the client cannot contact the server due to an 658 * underlying communication problem. 659 */ 660 <C extends ConfigurationClient, S extends Configuration> 661 void removeChild(OptionalRelationDefinition<C, S> r) 662 throws IllegalArgumentException, ManagedObjectNotFoundException, 663 OperationRejectedException, ConcurrentModificationException, 664 AuthorizationException, CommunicationException; 665 666 667 668 /** 669 * Sets a new pending value for the specified property. 670 * <p> 671 * See the class description for more information regarding pending 672 * values. 673 * 674 * @param <PD> 675 * The type of the property to be modified. 676 * @param pd 677 * The property to be modified. 678 * @param value 679 * The new pending value for the property, or 680 * <code>null</code> if the property should be reset to 681 * its default behavior. 682 * @throws IllegalPropertyValueException 683 * If the new pending value is deemed to be invalid 684 * according to the property definition. 685 * @throws PropertyIsReadOnlyException 686 * If this is not a new managed object and the property is 687 * read-only or for monitoring purposes. 688 * @throws PropertyIsMandatoryException 689 * If an attempt was made to remove a mandatory property. 690 * @throws IllegalArgumentException 691 * If the specified property definition is not associated 692 * with this managed object. 693 */ 694 <PD> void setPropertyValue(PropertyDefinition<PD> pd, PD value) 695 throws IllegalPropertyValueException, PropertyIsReadOnlyException, 696 PropertyIsMandatoryException, IllegalArgumentException; 697 698 699 700 /** 701 * Sets a new pending values for the specified property. 702 * <p> 703 * See the class description for more information regarding pending 704 * values. 705 * 706 * @param <PD> 707 * The type of the property to be modified. 708 * @param pd 709 * The property to be modified. 710 * @param values 711 * A non-<code>null</code> set of new pending values for 712 * the property (an empty set indicates that the property 713 * should be reset to its default behavior). The set will 714 * not be referenced by this managed object. 715 * @throws IllegalPropertyValueException 716 * If a new pending value is deemed to be invalid 717 * according to the property definition. 718 * @throws PropertyIsSingleValuedException 719 * If an attempt was made to add multiple pending values 720 * to a single-valued property. 721 * @throws PropertyIsReadOnlyException 722 * If this is not a new managed object and the property is 723 * read-only or for monitoring purposes. 724 * @throws PropertyIsMandatoryException 725 * If an attempt was made to remove a mandatory property. 726 * @throws IllegalArgumentException 727 * If the specified property definition is not associated 728 * with this managed object. 729 */ 730 <PD> void setPropertyValues(PropertyDefinition<PD> pd, Collection<PD> values) 731 throws IllegalPropertyValueException, PropertyIsSingleValuedException, 732 PropertyIsReadOnlyException, PropertyIsMandatoryException, 733 IllegalArgumentException; 734 735 }