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 2008-2009 Sun Microsystems, Inc.
025 *      Portions Copyright 2014-2015 ForgeRock AS
026 */
027package org.forgerock.opendj.config.client;
028
029import java.io.Closeable;
030import java.util.SortedSet;
031
032import org.forgerock.opendj.config.AbstractManagedObjectDefinition;
033import org.forgerock.opendj.config.Configuration;
034import org.forgerock.opendj.config.ConfigurationClient;
035import org.forgerock.opendj.config.DefinitionDecodingException;
036import org.forgerock.opendj.config.InstantiableRelationDefinition;
037import org.forgerock.opendj.config.ManagedObjectNotFoundException;
038import org.forgerock.opendj.config.ManagedObjectPath;
039import org.forgerock.opendj.config.OptionalRelationDefinition;
040import org.forgerock.opendj.config.PropertyDefinition;
041import org.forgerock.opendj.config.PropertyException;
042import org.forgerock.opendj.config.SetRelationDefinition;
043import org.forgerock.opendj.ldap.LdapException;
044import org.forgerock.opendj.server.config.client.RootCfgClient;
045
046/**
047 * Client management connection context.
048 */
049public interface ManagementContext extends Closeable {
050
051    /**
052     * Deletes the named instantiable child managed object from the named parent
053     * managed object.
054     *
055     * @param <C>
056     *            The type of client managed object configuration that the
057     *            relation definition refers to.
058     * @param <S>
059     *            The type of server managed object configuration that the
060     *            relation definition refers to.
061     * @param parent
062     *            The path of the parent managed object.
063     * @param rd
064     *            The instantiable relation definition.
065     * @param name
066     *            The name of the child managed object to be removed.
067     * @return Returns <code>true</code> if the named instantiable child managed
068     *         object was found, or <code>false</code> if it was not found.
069     * @throws IllegalArgumentException
070     *             If the relation definition is not associated with the parent
071     *             managed object's definition.
072     * @throws ManagedObjectNotFoundException
073     *             If the parent managed object could not be found.
074     * @throws OperationRejectedException
075     *             If the managed object cannot be removed due to some
076     *             client-side or server-side constraint which cannot be
077     *             satisfied (for example, if it is referenced by another
078     *             managed object).
079     * @throws LdapException
080     *             If any other error occurs.
081     */
082    <C extends ConfigurationClient, S extends Configuration> boolean deleteManagedObject(
083            ManagedObjectPath<?, ?> parent, InstantiableRelationDefinition<C, S> rd, String name)
084            throws ManagedObjectNotFoundException, OperationRejectedException, LdapException;
085
086    /**
087     * Deletes the optional child managed object from the named parent managed
088     * object.
089     *
090     * @param <C>
091     *            The type of client managed object configuration that the
092     *            relation definition refers to.
093     * @param <S>
094     *            The type of server managed object configuration that the
095     *            relation definition refers to.
096     * @param parent
097     *            The path of the parent managed object.
098     * @param rd
099     *            The optional relation definition.
100     * @return Returns <code>true</code> if the optional child managed object
101     *         was found, or <code>false</code> if it was not found.
102     * @throws IllegalArgumentException
103     *             If the relation definition is not associated with the parent
104     *             managed object's definition.
105     * @throws ManagedObjectNotFoundException
106     *             If the parent managed object could not be found.
107     * @throws OperationRejectedException
108     *             If the managed object cannot be removed due to some
109     *             client-side or server-side constraint which cannot be
110     *             satisfied (for example, if it is referenced by another
111     *             managed object).
112     * @throws LdapException
113     *             If any other error occurs.
114     */
115    <C extends ConfigurationClient, S extends Configuration> boolean deleteManagedObject(
116            ManagedObjectPath<?, ?> parent, OptionalRelationDefinition<C, S> rd) throws
117            ManagedObjectNotFoundException, OperationRejectedException, LdapException;
118
119    /**
120     * Deletes s set child managed object from the named parent managed object.
121     *
122     * @param <C>
123     *            The type of client managed object configuration that the
124     *            relation definition refers to.
125     * @param <S>
126     *            The type of server managed object configuration that the
127     *            relation definition refers to.
128     * @param parent
129     *            The path of the parent managed object.
130     * @param rd
131     *            The set relation definition.
132     * @param name
133     *            The name of the child managed object to be removed.
134     * @return Returns <code>true</code> if the set child managed object was
135     *         found, or <code>false</code> if it was not found.
136     * @throws IllegalArgumentException
137     *             If the relation definition is not associated with the parent
138     *             managed object's definition.
139     * @throws ManagedObjectNotFoundException
140     *             If the parent managed object could not be found.
141     * @throws OperationRejectedException
142     *             If the managed object cannot be removed due to some
143     *             client-side or server-side constraint which cannot be
144     *             satisfied (for example, if it is referenced by another
145     *             managed object).
146     * @throws LdapException
147     *             If any other error occurs.
148     */
149    <C extends ConfigurationClient, S extends Configuration> boolean deleteManagedObject(
150            ManagedObjectPath<?, ?> parent, SetRelationDefinition<C, S> rd, String name)
151            throws ManagedObjectNotFoundException, OperationRejectedException, LdapException;
152
153    /**
154     * Gets the named managed object.
155     *
156     * @param <C>
157     *            The type of client managed object configuration that the path
158     *            definition refers to.
159     * @param <S>
160     *            The type of server managed object configuration that the path
161     *            definition refers to.
162     * @param path
163     *            The path of the managed object.
164     * @return Returns the named managed object.
165     * @throws DefinitionDecodingException
166     *             If the managed object was found but its type could not be
167     *             determined.
168     * @throws ManagedObjectDecodingException
169     *             If the managed object was found but one or more of its
170     *             properties could not be decoded.
171     * @throws ManagedObjectNotFoundException
172     *             If the requested managed object could not be found on the
173     *             server.
174     * @throws LdapException
175     *             If any other error occurs.
176     */
177    <C extends ConfigurationClient, S extends Configuration> ManagedObject<? extends C> getManagedObject(
178            ManagedObjectPath<C, S> path) throws DefinitionDecodingException, ManagedObjectDecodingException,
179            ManagedObjectNotFoundException, LdapException;
180
181    /**
182     * Gets the effective value of a property in the named managed object.
183     *
184     * @param <P>
185     *            The type of the property to be retrieved.
186     * @param path
187     *            The path of the managed object containing the property.
188     * @param pd
189     *            The property to be retrieved.
190     * @return Returns the property's effective value, or <code>null</code> if
191     *         there are no values defined.
192     * @throws IllegalArgumentException
193     *             If the property definition is not associated with the
194     *             referenced managed object's definition.
195     * @throws DefinitionDecodingException
196     *             If the managed object was found but its type could not be
197     *             determined.
198     * @throws PropertyException
199     *             If the managed object was found but the requested property
200     *             could not be decoded.
201     * @throws ManagedObjectNotFoundException
202     *             If the requested managed object could not be found on the
203     *             server.
204     * @throws LdapException
205     *             If any other error occurs.
206     */
207    <P> P getPropertyValue(ManagedObjectPath<?, ?> path, PropertyDefinition<P> pd)
208            throws DefinitionDecodingException, LdapException, ManagedObjectNotFoundException;
209
210    /**
211     * Gets the effective values of a property in the named managed object.
212     *
213     * @param <P>
214     *            The type of the property to be retrieved.
215     * @param path
216     *            The path of the managed object containing the property.
217     * @param pd
218     *            The property to be retrieved.
219     * @return Returns the property's effective values, or an empty set if there
220     *         are no values defined.
221     * @throws IllegalArgumentException
222     *             If the property definition is not associated with the
223     *             referenced managed object's definition.
224     * @throws DefinitionDecodingException
225     *             If the managed object was found but its type could not be
226     *             determined.
227     * @throws PropertyException
228     *             If the managed object was found but the requested property
229     *             could not be decoded.
230     * @throws ManagedObjectNotFoundException
231     *             If the requested managed object could not be found on the
232     *             server.
233     * @throws LdapException
234     *             If any other error occurs.
235     */
236    <P> SortedSet<P> getPropertyValues(ManagedObjectPath<?, ?> path, PropertyDefinition<P> pd)
237            throws DefinitionDecodingException, LdapException, ManagedObjectNotFoundException;
238
239    /**
240     * Gets the root configuration client associated with this management
241     * context.
242     *
243     * @return Returns the root configuration client associated with this
244     *         management context.
245     */
246    RootCfgClient getRootConfiguration();
247
248    /**
249     * Gets the root configuration managed object associated with this
250     * management context.
251     *
252     * @return Returns the root configuration managed object associated with
253     *         this management context.
254     */
255    ManagedObject<RootCfgClient> getRootConfigurationManagedObject();
256
257    /**
258     * Lists the child managed objects of the named parent managed object.
259     *
260     * @param <C>
261     *            The type of client managed object configuration that the
262     *            relation definition refers to.
263     * @param <S>
264     *            The type of server managed object configuration that the
265     *            relation definition refers to.
266     * @param parent
267     *            The path of the parent managed object.
268     * @param rd
269     *            The instantiable relation definition.
270     * @return Returns the names of the child managed objects.
271     * @throws IllegalArgumentException
272     *             If the relation definition is not associated with the parent
273     *             managed object's definition.
274     * @throws ManagedObjectNotFoundException
275     *             If the parent managed object could not be found.
276     * @throws LdapException
277     *             If any other error occurs.
278     */
279    <C extends ConfigurationClient, S extends Configuration> String[] listManagedObjects(
280            ManagedObjectPath<?, ?> parent, InstantiableRelationDefinition<C, S> rd) throws
281            ManagedObjectNotFoundException, LdapException;
282
283    /**
284     * Lists the child managed objects of the named parent managed object which
285     * are a sub-type of the specified managed object definition.
286     *
287     * @param <C>
288     *            The type of client managed object configuration that the
289     *            relation definition refers to.
290     * @param <S>
291     *            The type of server managed object configuration that the
292     *            relation definition refers to.
293     * @param parent
294     *            The path of the parent managed object.
295     * @param rd
296     *            The instantiable relation definition.
297     * @param d
298     *            The managed object definition.
299     * @return Returns the names of the child managed objects which are a
300     *         sub-type of the specified managed object definition.
301     * @throws IllegalArgumentException
302     *             If the relation definition is not associated with the parent
303     *             managed object's definition.
304     * @throws ManagedObjectNotFoundException
305     *             If the parent managed object could not be found.
306     * @throws LdapException
307     *             If any other error occurs.
308     */
309    <C extends ConfigurationClient, S extends Configuration> String[] listManagedObjects(
310            ManagedObjectPath<?, ?> parent, InstantiableRelationDefinition<C, S> rd,
311            AbstractManagedObjectDefinition<? extends C, ? extends S> d) throws
312            ManagedObjectNotFoundException, LdapException;
313
314    /**
315     * Lists the child managed objects of the named parent managed object.
316     *
317     * @param <C>
318     *            The type of client managed object configuration that the
319     *            relation definition refers to.
320     * @param <S>
321     *            The type of server managed object configuration that the
322     *            relation definition refers to.
323     * @param parent
324     *            The path of the parent managed object.
325     * @param rd
326     *            The set relation definition.
327     * @return Returns the names of the child managed objects.
328     * @throws IllegalArgumentException
329     *             If the relation definition is not associated with the parent
330     *             managed object's definition.
331     * @throws ManagedObjectNotFoundException
332     *             If the parent managed object could not be found.
333     * @throws LdapException
334     *             If any other error occurs.
335     */
336    <C extends ConfigurationClient, S extends Configuration> String[] listManagedObjects(
337            ManagedObjectPath<?, ?> parent, SetRelationDefinition<C, S> rd) throws
338            ManagedObjectNotFoundException, LdapException;
339
340    /**
341     * Determines whether or not the named managed object exists.
342     *
343     * @param path
344     *            The path of the named managed object.
345     * @return Returns <code>true</code> if the named managed object exists,
346     *         <code>false</code> otherwise.
347     * @throws ManagedObjectNotFoundException
348     *             If the parent managed object could not be found.
349     * @throws LdapException
350     *             If any other error occurs.
351     */
352    boolean managedObjectExists(ManagedObjectPath<?, ?> path) throws ManagedObjectNotFoundException, LdapException;
353}