001/*
002 * Copyright 2007-2017 UnboundID Corp.
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2008-2017 UnboundID Corp.
007 *
008 * This program is free software; you can redistribute it and/or modify
009 * it under the terms of the GNU General Public License (GPLv2 only)
010 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
011 * as published by the Free Software Foundation.
012 *
013 * This program is distributed in the hope that it will be useful,
014 * but WITHOUT ANY WARRANTY; without even the implied warranty of
015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
016 * GNU General Public License for more details.
017 *
018 * You should have received a copy of the GNU General Public License
019 * along with this program; if not, see <http://www.gnu.org/licenses>.
020 */
021package com.unboundid.ldap.sdk;
022
023
024
025import java.util.List;
026
027import com.unboundid.util.NotExtensible;
028import com.unboundid.util.ThreadSafety;
029import com.unboundid.util.ThreadSafetyLevel;
030
031
032
033/**
034 * This interface defines a set of methods that may be safely called in an LDAP
035 * search request without altering its contents.  This interface must not be
036 * implemented by any class other than {@link SearchRequest}.
037 * <BR><BR>
038 * This interface does not inherently provide the assurance of thread safety for
039 * the methods that it exposes, because it is still possible for a thread
040 * referencing the object which implements this interface to alter the request
041 * using methods not included in this interface.  However, if it can be
042 * guaranteed that no thread will alter the underlying object, then the methods
043 * exposed by this interface can be safely invoked concurrently by any number of
044 * threads.
045 */
046@NotExtensible()
047@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_NOT_THREADSAFE)
048public interface ReadOnlySearchRequest
049       extends ReadOnlyLDAPRequest
050{
051  /**
052   * Retrieves the base DN for this search request.
053   *
054   * @return  The base DN for this search request.
055   */
056  String getBaseDN();
057
058
059
060  /**
061   * Retrieves the scope for this search request.
062   *
063   * @return  The scope for this search request.
064   */
065  SearchScope getScope();
066
067
068
069  /**
070   * Retrieves the dereference policy that should be used by the server for any
071   * aliases encountered during search processing.
072   *
073   * @return  The dereference policy that should be used by the server for any
074   *          aliases encountered during search processing.
075   */
076  DereferencePolicy getDereferencePolicy();
077
078
079
080  /**
081   * Retrieves the maximum number of entries that should be returned by the
082   * server when processing this search request.
083   *
084   * @return  The maximum number of entries that should be returned by the
085   *          server when processing this search request, or zero if there is
086   *          no limit.
087   */
088  int getSizeLimit();
089
090
091
092  /**
093   * Retrieves the maximum length of time in seconds that the server should
094   * spend processing this search request.
095   *
096   * @return  The maximum length of time in seconds that the server should
097   *          spend processing this search request, or zero if there is no
098   *          limit.
099   */
100  int getTimeLimitSeconds();
101
102
103
104  /**
105   * Indicates whether the server should return only attribute names in matching
106   * entries, rather than both names and values.
107   *
108   * @return  {@code true} if matching entries should include only attribute
109   *          names, or {@code false} if matching entries should include both
110   *          attribute names and values.
111   */
112  boolean typesOnly();
113
114
115
116  /**
117   * Retrieves the filter that should be used to identify matching entries.
118   *
119   * @return  The filter that should be used to identify matching entries.
120   */
121  Filter getFilter();
122
123
124
125  /**
126   * Retrieves the set of requested attributes to include in matching entries.
127   *
128   * @return  The set of requested attributes to include in matching entries, or
129   *          an empty array if the default set of attributes (all user
130   *          attributes but no operational attributes) should be requested.
131   */
132  List<String> getAttributeList();
133
134
135
136  /**
137   * {@inheritDoc}
138   */
139  SearchRequest duplicate();
140
141
142
143  /**
144   * {@inheritDoc}
145   */
146  SearchRequest duplicate(final Control[] controls);
147}