001    /*
002     * Copyright 2007-2015 UnboundID Corp.
003     * All Rights Reserved.
004     */
005    /*
006     * Copyright (C) 2008-2015 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     */
021    package com.unboundid.ldap.sdk;
022    
023    
024    
025    import java.io.Serializable;
026    import java.util.List;
027    
028    import com.unboundid.util.NotExtensible;
029    import com.unboundid.util.ThreadSafety;
030    import com.unboundid.util.ThreadSafetyLevel;
031    
032    
033    
034    /**
035     * This interface defines a set of methods that may be safely called in an LDAP
036     * request without altering its contents.  This interface must not be
037     * implemented by any class outside of the LDAP SDK.
038     * <BR><BR>
039     * This interface does not inherently provide the assurance of thread safety for
040     * the methods that it exposes, because it is still possible for a thread
041     * referencing the object which implements this interface to alter the request
042     * using methods not included in this interface.  However, if it can be
043     * guaranteed that no thread will alter the underlying object, then the methods
044     * exposed by this interface can be safely invoked concurrently by any number of
045     * threads.
046     */
047    @NotExtensible()
048    @ThreadSafety(level=ThreadSafetyLevel.INTERFACE_NOT_THREADSAFE)
049    public interface ReadOnlyLDAPRequest
050           extends Serializable
051    {
052      /**
053       * Retrieves a list containing the set of controls for this request.
054       *
055       * @return  A list containing the set of controls for this request.
056       */
057      List<Control> getControlList();
058    
059    
060    
061      /**
062       * Indicates whether this request contains at least one control.
063       *
064       * @return  {@code true} if this request contains at least one control, or
065       *          {@code false} if not.
066       */
067      boolean hasControl();
068    
069    
070    
071      /**
072       * Indicates whether this request contains at least one control with the
073       * specified OID.
074       *
075       * @param  oid  The object identifier for which to make the determination.  It
076       *              must not be {@code null}.
077       *
078       * @return  {@code true} if this request contains at least one control with
079       *          the specified OID, or {@code false} if not.
080       */
081      boolean hasControl(final String oid);
082    
083    
084    
085      /**
086       * Retrieves the control with the specified OID from this request.  If this
087       * request has multiple controls with the specified OID, then the first will
088       * be returned.
089       *
090       * @param  oid  The object identifier for which to retrieve the corresponding
091       *              control.  It must not be {@code null}.
092       *
093       * @return  The first control found with the specified OID, or {@code null} if
094       *          no control with that OID is included in this request.
095       */
096      Control getControl(final String oid);
097    
098    
099    
100      /**
101       * Retrieves the maximum length of time in milliseconds that processing on
102       * this operation should be allowed to block while waiting for a response from
103       * the server.
104       *
105       * @param  connection  The connection to use in order to retrieve the default
106       *                     value, if appropriate.  It may be {@code null} to
107       *                     retrieve the request-specific timeout (which may be
108       *                     negative if no response-specific timeout has been set).
109       *
110       * @return  The maximum length of time in milliseconds that processing on this
111       *          operation should be allowed to block while waiting for a response
112       *          from the server, or zero if no timeout should be enforced.
113       */
114      long getResponseTimeoutMillis(final LDAPConnection connection);
115    
116    
117    
118      /**
119       * Indicates whether to automatically follow any referrals encountered while
120       * processing this request.  If a value has been set for this request, then it
121       * will be returned.  Otherwise, the default from the connection options for
122       * the provided connection will be used.
123       *
124       * @param  connection  The connection whose connection options may be used in
125       *                     the course of making the determination.  It must not
126       *                     be {@code null}.
127       *
128       * @return  {@code true} if any referrals encountered during processing should
129       *          be automatically followed, or {@code false} if not.
130       */
131      boolean followReferrals(final LDAPConnection connection);
132    
133    
134    
135      /**
136       * Creates a new instance of this LDAP request that may be modified without
137       * impacting this request.
138       *
139       * @return  A new instance of this LDAP request that may be modified without
140       *          impacting this request.
141       */
142      LDAPRequest duplicate();
143    
144    
145    
146      /**
147       * Creates a new instance of this LDAP request that may be modified without
148       * impacting this request.  The provided controls will be used for the new
149       * request instead of duplicating the controls from this request.
150       *
151       * @param  controls  The set of controls to include in the duplicate request.
152       *
153       * @return  A new instance of this LDAP request that may be modified without
154       *          impacting this request.
155       */
156      LDAPRequest duplicate(final Control[] controls);
157    
158    
159    
160      /**
161       * Retrieves a string representation of this request.
162       *
163       * @return  A string representation of this request.
164       */
165      @Override()
166      String toString();
167    
168    
169    
170      /**
171       * Appends a string representation of this request to the provided buffer.
172       *
173       * @param  buffer  The buffer to which to append a string representation of
174       *                 this request.
175       */
176      void toString(final StringBuilder buffer);
177    }