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