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