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 }