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 * docs/licenses/cddl.txt
011 * or http://www.opensource.org/licenses/cddl1.php.
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 * docs/licenses/cddl.txt.  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 2011-2021 Ping Identity Corporation
026 */
027package com.unboundid.directory.sdk.ds.types;
028
029import com.unboundid.directory.sdk.common.types.Entry;
030import com.unboundid.ldap.sdk.Filter;
031import com.unboundid.ldap.sdk.LDAPException;
032import com.unboundid.util.NotExtensible;
033import com.unboundid.util.ThreadSafety;
034import com.unboundid.util.ThreadSafetyLevel;
035
036/**
037 * This interface defines a set of methods that may be used to interact with a
038 * backend that has been defined in the server.
039 */
040@NotExtensible()
041@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
042public interface BackendContext
043{
044
045  /**
046   * Retrieves the backend ID for this backend.
047   *
048   * @return  The backend ID for this backend.
049   */
050  String getBackendID();
051
052
053
054  /**
055   * Retrieves the set of base DNs handled by the backend.
056   *
057   * @return  The set of base DNs handled by the backend.
058   */
059  String[] getBaseDNs();
060
061
062
063  /**
064   * Retrieves the total number of entries contained in this backend,
065   * if that information is available.
066   *
067   * @return  The total number of entries contained in this backend,
068   *          or -1 if that information is not available.
069   */
070  long getEntryCount();
071
072
073
074  /**
075   * Indicates whether the backend is considered local (i.e., holds data in a
076   * repository that is local to and entirely managed by the server).
077   *
078   * @return  {@code true} if the backend should be considered local, or
079   *          {@code false} if the data may be held in some external repository.
080   */
081  boolean isLocal();
082
083
084
085  /**
086   * Indicates whether the backend is considered a private backend (with data
087   * generated and/or maintained by the server) rather than a public backend
088   * (with user data provided and managed by clients).
089   *
090   * @return  {@code true} if the backend is considered a private backend within
091   *          the server, or {@code false} if it is a public backend.
092   */
093  boolean isPrivateBackend();
094
095
096
097  /**
098   * Retrieves the {@link WritabilityMode} for the backend.
099   *
100   * @return  The {@link WritabilityMode} for the backend.
101   */
102  WritabilityMode getWritabilityMode();
103
104
105
106  /**
107   * Indicates whether the backend considers filter components involving the
108   * specified attribute type and index type indexed. This may include
109   * attribute types for which an index has been explicitly configured in the
110   * backend, as well as attributes which are automatically considered indexed
111   * (e.g., because the backend holds only a small amount of data and considers
112   * all attributes indexed).
113   *
114   * @param  attributeType  The name or OID of the attribute type for which to
115   *                        make the determination. It must not be
116   *                        {@code null}.
117   * @param  indexType      The {@link IndexType} for which to make the
118   *                        determination. It must not be {@code null}.
119   *
120   * @return  {@code true} if the specified attribute type is indexed for the
121   *          given type of matching, or {@code false} if not.
122   */
123  boolean isIndexed(final String attributeType, final IndexType indexType);
124
125
126
127  /**
128   * Indicates whether the backend has been explicitly configured with an
129   * index for the specified attribute type and index type.
130   *
131   * @param  attributeType  The name or OID of the attribute type for which to
132   *                        make the determination. It must not be
133   *                        {@code null}.
134   * @param  indexType      The {@link IndexType} for which to make the
135   *                        determination. It must not be {@code null}.
136   *
137   * @return  {@code true} if the specified attribute type is indexed for the
138   *          given type of matching, or {@code false} if not.
139   */
140  boolean isExplicitlyIndexed(final String attributeType,
141                              final IndexType indexType);
142
143
144
145  /**
146   * Indicates whether the backend may consider a search with the provided
147   * filter as indexed.
148   *
149   * @param  filter  The {@link Filter} for which to make the determination.
150   *                 It must not be {@code null}.
151   *
152   * @return  {@code true} if a search with the provided filter may be
153   *          considered indexed in the backend, or {@code false} if not.
154   */
155  boolean isIndexed(final Filter filter);
156
157
158
159  /**
160   * Indicates whether the specified entry exists in the backend.
161   *
162   * @param  dn  The DN for which to make the determination. It must not be
163   *             {@code null}.
164   *
165   * @return  {@code true} if the specified entry exists in the backend, or
166   *          {@code false} if not.
167   *
168   * @throws  LDAPException  If the provided string cannot be parsed as a valid
169   *                         DN or if a problem is encountered while making the
170   *                         determination.
171   */
172  boolean entryExists(final String dn) throws LDAPException;
173
174
175
176  /**
177   * Retrieves the specified entry from the backend.
178   *
179   * @param  dn  The DN for which to make the determination. It must not be
180   *             {@code null}.
181   *
182   * @return  The entry with the specified DN, or {@code null} if the entry does
183   *          not exist in the backend.
184   *
185   * @throws  LDAPException  If the provided string cannot be parsed as a valid
186   *                         DN or if a problem is encountered while attempting
187   *                         to retrieve it.
188   */
189  Entry getEntry(final String dn) throws LDAPException;
190
191
192
193  /**
194   * Indicates whether this backend should contain the entry with the specified
195   * DN.
196   *
197   * @param dn  The DN of the entry for which to make the determination.
198   *
199   * @return  {@code true} if this backend handles operations for the
200   *          provided entry, or {@code false} if it does not.
201   *
202   * @throws  LDAPException  If the provided string cannot be parsed as a valid
203   *                         DN or if a problem is encountered while making the
204   *                         determination.
205   */
206   boolean handlesEntry(String dn) throws LDAPException;
207
208
209
210  /**
211   * Retrieves information about the parent for the associated backend, if any.
212   *
213   * @return  Information about the parent for the associated backend, or
214   *          {@code null} if the backend does not have a parent.
215   */
216  BackendContext getParentBackend();
217
218
219
220  /**
221   * Retrieves information about any backends which are immediately subordinate
222   * to the associated backend.
223   *
224   * @return  Information about any backends which are immediately subordinate
225   *          to the associated backend, or an empty array if there are no
226   *          subordinate backends.
227   */
228  BackendContext[] getSubordinateBackends();
229}