001/*
002 * Copyright 2007-2024 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright 2007-2024 Ping Identity Corporation
007 *
008 * Licensed under the Apache License, Version 2.0 (the "License");
009 * you may not use this file except in compliance with the License.
010 * You may obtain a copy of the License at
011 *
012 *    http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing, software
015 * distributed under the License is distributed on an "AS IS" BASIS,
016 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017 * See the License for the specific language governing permissions and
018 * limitations under the License.
019 */
020/*
021 * Copyright (C) 2007-2024 Ping Identity Corporation
022 *
023 * This program is free software; you can redistribute it and/or modify
024 * it under the terms of the GNU General Public License (GPLv2 only)
025 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
026 * as published by the Free Software Foundation.
027 *
028 * This program is distributed in the hope that it will be useful,
029 * but WITHOUT ANY WARRANTY; without even the implied warranty of
030 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
031 * GNU General Public License for more details.
032 *
033 * You should have received a copy of the GNU General Public License
034 * along with this program; if not, see <http://www.gnu.org/licenses>.
035 */
036package com.unboundid.ldap.sdk;
037
038
039
040import java.util.List;
041
042import com.unboundid.ldap.matchingrules.MatchingRule;
043import com.unboundid.ldif.LDIFAddChangeRecord;
044import com.unboundid.util.NotExtensible;
045import com.unboundid.util.NotNull;
046import com.unboundid.util.Nullable;
047import com.unboundid.util.ThreadSafety;
048import com.unboundid.util.ThreadSafetyLevel;
049
050
051
052/**
053 * This interface defines a set of methods that may be safely called in an LDAP
054 * add request without altering its contents.  This interface must not be
055 * implemented by any class other than {@link AddRequest}.
056 * <BR><BR>
057 * This interface does not inherently provide the assurance of thread safety for
058 * the methods that it exposes, because it is still possible for a thread
059 * referencing the object which implements this interface to alter the request
060 * using methods not included in this interface.  However, if it can be
061 * guaranteed that no thread will alter the underlying object, then the methods
062 * exposed by this interface can be safely invoked concurrently by any number of
063 * threads.
064 */
065@NotExtensible()
066@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_NOT_THREADSAFE)
067public interface ReadOnlyAddRequest
068       extends ReadOnlyLDAPRequest
069{
070  /**
071   * Retrieves the DN for this add request.
072   *
073   * @return  The DN for this add request.
074   */
075  @NotNull()
076  String getDN();
077
078
079
080  /**
081   * Retrieves the set of attributes for this add request.
082   *
083   * @return  The set of attributes for this add request.
084   */
085  @NotNull()
086  List<Attribute> getAttributes();
087
088
089
090  /**
091   * Retrieves the specified attribute from this add request.
092   *
093   * @param  attributeName  The name of the attribute to retrieve.  It must not
094   *                        be {@code null}.
095   *
096   * @return  The requested attribute, or {@code null} if it does not exist in
097   *          the add request.
098   */
099  @Nullable()
100  Attribute getAttribute(@NotNull String attributeName);
101
102
103
104  /**
105   * Indicates whether this add request contains the specified attribute.
106   *
107   * @param  attributeName  The name of the attribute for which to make the
108   *                        determination.  It must not be {@code null}.
109   *
110   * @return  {@code true} if this add request contains the specified attribute,
111   *          or {@code false} if not.
112   */
113  boolean hasAttribute(@NotNull String attributeName);
114
115
116
117  /**
118   * Indicates whether this add request contains the specified attribute.  It
119   * will only return {@code true} if this add request contains an attribute
120   * with the same name and exact set of values.
121   *
122   * @param  attribute  The attribute for which to make the determination.  It
123   *                    must not be {@code null}.
124   *
125   * @return  {@code true} if this add request contains the specified attribute,
126   *          or {@code false} if not.
127   */
128  boolean hasAttribute(@NotNull Attribute attribute);
129
130
131
132  /**
133   * Indicates whether this add request contains an attribute with the given
134   * name and value.
135   *
136   * @param  attributeName   The name of the attribute for which to make the
137   *                         determination.  It must not be {@code null}.
138   * @param  attributeValue  The value for which to make the determination.  It
139   *                         must not be {@code null}.
140   *
141   * @return  {@code true} if this add request contains an attribute with the
142   *          specified name and value, or {@code false} if not.
143   */
144  boolean hasAttributeValue(@NotNull String attributeName,
145                            @NotNull String attributeValue);
146
147
148
149  /**
150   * Indicates whether this add request contains an attribute with the given
151   * name and value.
152   *
153   * @param  attributeName   The name of the attribute for which to make the
154   *                         determination.  It must not be {@code null}.
155   * @param  attributeValue  The value for which to make the determination.  It
156   *                         must not be {@code null}.
157   * @param  matchingRule    The matching rule to use to make the determination.
158   *                         It must not be {@code null}.
159   *
160   * @return  {@code true} if this add request contains an attribute with the
161   *          specified name and value, or {@code false} if not.
162   */
163  boolean hasAttributeValue(@NotNull String attributeName,
164                            @NotNull String attributeValue,
165                            @NotNull MatchingRule matchingRule);
166
167
168
169  /**
170   * Indicates whether this add request contains an attribute with the given
171   * name and value.
172   *
173   * @param  attributeName   The name of the attribute for which to make the
174   *                         determination.  It must not be {@code null}.
175   * @param  attributeValue  The value for which to make the determination.  It
176   *                         must not be {@code null}.
177   *
178   * @return  {@code true} if this add request  contains an attribute with the
179   *          specified name and value, or {@code false} if not.
180   */
181  boolean hasAttributeValue(@NotNull String attributeName,
182                            @NotNull byte[] attributeValue);
183
184
185
186  /**
187   * Indicates whether this add request contains an attribute with the given
188   * name and value.
189   *
190   * @param  attributeName   The name of the attribute for which to make the
191   *                         determination.  It must not be {@code null}.
192   * @param  attributeValue  The value for which to make the determination.  It
193   *                         must not be {@code null}.
194   * @param  matchingRule    The matching rule to use to make the determination.
195   *                         It must not be {@code null}.
196   *
197   * @return  {@code true} if this add request  contains an attribute with the
198   *          specified name and value, or {@code false} if not.
199   */
200  boolean hasAttributeValue(@NotNull String attributeName,
201                            @NotNull byte[] attributeValue,
202                            @NotNull MatchingRule matchingRule);
203
204
205
206  /**
207   * Indicates whether this add request contains the specified object class.
208   *
209   * @param  objectClassName  The name of the object class for which to make the
210   *                          determination.  It must not be {@code null}.
211   *
212   * @return  {@code true} if this add request contains the specified object
213   *          class, or {@code false} if not.
214   */
215  boolean hasObjectClass(@NotNull String objectClassName);
216
217
218
219  /**
220   * Retrieves an {@code Entry} object containing the DN and attributes of this
221   * add request.
222   *
223   * @return  An {@code Entry} object containing the DN and attributes of this
224   *          add request.
225   */
226  @NotNull()
227  Entry toEntry();
228
229
230
231  /**
232   * {@inheritDoc}
233   */
234  @Override()
235  @NotNull()
236  AddRequest duplicate();
237
238
239
240  /**
241   * {@inheritDoc}
242   */
243  @Override()
244  @NotNull()
245  AddRequest duplicate(@Nullable Control[] controls);
246
247
248
249  /**
250   * Retrieves an LDIF add change record with the contents of this add request.
251   *
252   * @return  An LDIF add change record with the contents of this add request.
253   */
254  @NotNull()
255  LDIFAddChangeRecord toLDIFChangeRecord();
256
257
258
259  /**
260   * Retrieves a string array whose lines contain an LDIF representation of the
261   * corresponding add change record.
262   *
263   * @return  A string array whose lines contain an LDIF representation of the
264   *          corresponding add change record.
265   */
266  @NotNull()
267  String[] toLDIF();
268
269
270
271  /**
272   * Retrieves an LDIF string representation of this add request.
273   *
274   * @return  An LDIF string representation of this add request.
275   */
276  @NotNull()
277  String toLDIFString();
278}