Class SearchRequest

  • All Implemented Interfaces:
    ProtocolOp, ReadOnlyLDAPRequest, ReadOnlySearchRequest, java.io.Serializable

    @Mutable
    @ThreadSafety(level=NOT_THREADSAFE)
    public final class SearchRequest
    extends UpdatableLDAPRequest
    implements ReadOnlySearchRequest, ProtocolOp
    This class implements the processing necessary to perform an LDAPv3 search operation, which can be used to retrieve entries that match a given set of criteria. A search request may include the following elements:
    • Base DN -- Specifies the base DN for the search. Only entries at or below this location in the server (based on the scope) will be considered potential matches.
    • Scope -- Specifies the range of entries relative to the base DN that may be considered potential matches.
    • Dereference Policy -- Specifies the behavior that the server should exhibit if any alias entries are encountered while processing the search. If no dereference policy is provided, then a default of DereferencePolicy.NEVER will be used.
    • Size Limit -- Specifies the maximum number of entries that should be returned from the search. A value of zero indicates that there should not be any limit enforced. Note that the directory server may also be configured with a server-side size limit which can also limit the number of entries that may be returned to the client and in that case the smaller of the client-side and server-side limits will be used. If no size limit is provided, then a default of zero (unlimited) will be used.
    • Time Limit -- Specifies the maximum length of time in seconds that the server should spend processing the search. A value of zero indicates that there should not be any limit enforced. Note that the directory server may also be configured with a server-side time limit which can also limit the processing time, and in that case the smaller of the client-side and server-side limits will be used. If no time limit is provided, then a default of zero (unlimited) will be used.
    • Types Only -- Indicates whether matching entries should include only attribute names, or both attribute names and values. If no value is provided, then a default of false will be used.
    • Filter -- Specifies the criteria for determining which entries should be returned. See the Filter class for the types of filters that may be used.

      Note that filters can be specified using either their string representations or as Filter objects. As noted in the documentation for the Filter class, using the string representation may be somewhat dangerous if the data is not properly sanitized because special characters contained in the filter may cause it to be invalid or worse expose a vulnerability that could cause the filter to request more information than was intended. As a result, if the filter may include special characters or user-provided strings, then it is recommended that you use Filter objects created from their individual components rather than their string representations.
    • Attributes -- Specifies the set of attributes that should be included in matching entries. If no attributes are provided, then the server will default to returning all user attributes. If a specified set of attributes is given, then only those attributes will be included. Values that may be included to indicate a special meaning include:
      • NO_ATTRIBUTES -- Indicates that no attributes should be returned. That is, only the DNs of matching entries will be returned.
      • ALL_USER_ATTRIBUTES -- Indicates that all user attributes should be included in matching entries. This is the default if no attributes are provided, but this special value may be included if a specific set of operational attributes should be included along with all user attributes.
      • ALL_OPERATIONAL_ATTRIBUTES -- Indicates that all operational attributes should be included in matching entries.
      These special values may be used alone or in conjunction with each other and/or any specific attribute names or OIDs.
    • An optional set of controls to include in the request to send to the server.
    • An optional SearchResultListener which may be used to process search result entries and search result references returned by the server in the course of processing the request. If this is null, then the entries and references will be collected and returned in the SearchResult object that is returned.
    When processing a search operation, there are three ways that the returned entries and references may be accessed:

    SearchRequest objects are mutable and therefore can be altered and re-used for multiple requests. Note, however, that SearchRequest objects are not threadsafe and therefore a single SearchRequest object instance should not be used to process multiple requests at the same time.

    Example

    The following example demonstrates a simple search operation in which the client performs a search to find all users in the "Sales" department and then retrieves the name and e-mail address for each matching user:
     // Construct a filter that can be used to find everyone in the Sales
     // department, and then create a search request to find all such users
     // in the directory.
     Filter filter = Filter.createEqualityFilter("ou", "Sales");
     SearchRequest searchRequest =
          new SearchRequest("dc=example,dc=com", SearchScope.SUB, filter,
               "cn", "mail");
     SearchResult searchResult;
    
     try
     {
       searchResult = connection.search(searchRequest);
    
       for (SearchResultEntry entry : searchResult.getSearchEntries())
       {
         String name = entry.getAttributeValue("cn");
         String mail = entry.getAttributeValue("mail");
       }
     }
     catch (LDAPSearchException lse)
     {
       // The search failed for some reason.
       searchResult = lse.getSearchResult();
       ResultCode resultCode = lse.getResultCode();
       String errorMessageFromServer = lse.getDiagnosticMessage();
     }
     
    See Also:
    Serialized Form
    • Field Detail

      • ALL_USER_ATTRIBUTES

        @NotNull
        public static final java.lang.String ALL_USER_ATTRIBUTES
        The special value "*" that can be included in the set of requested attributes to indicate that all user attributes should be returned.
        See Also:
        Constant Field Values
      • ALL_OPERATIONAL_ATTRIBUTES

        @NotNull
        public static final java.lang.String ALL_OPERATIONAL_ATTRIBUTES
        The special value "+" that can be included in the set of requested attributes to indicate that all operational attributes should be returned.
        See Also:
        Constant Field Values
      • NO_ATTRIBUTES

        @NotNull
        public static final java.lang.String NO_ATTRIBUTES
        The special value "1.1" that can be included in the set of requested attributes to indicate that no attributes should be returned, with the exception of any other attributes explicitly named in the set of requested attributes.
        See Also:
        Constant Field Values
      • REQUEST_ATTRS_DEFAULT

        @NotNull
        public static final java.lang.String[] REQUEST_ATTRS_DEFAULT
        The default set of requested attributes that will be used, which will return all user attributes but no operational attributes.
    • Constructor Detail

      • SearchRequest

        public SearchRequest​(@NotNull
                             java.lang.String baseDN,
                             @NotNull
                             SearchScope scope,
                             @NotNull
                             java.lang.String filter,
                             @Nullable
                             java.lang.String... attributes)
                      throws LDAPException
        Creates a new search request with the provided information. Search result entries and references will be collected internally and included in the SearchResult object returned when search processing is completed.
        Parameters:
        baseDN - The base DN for the search request. It must not be null.
        scope - The scope that specifies the range of entries that should be examined for the search.
        filter - The string representation of the filter to use to identify matching entries. It must not be null.
        attributes - The set of attributes that should be returned in matching entries. It may be null or empty if the default attribute set (all user attributes) is to be requested.
        Throws:
        LDAPException - If the provided filter string cannot be parsed as an LDAP filter.
      • SearchRequest

        public SearchRequest​(@NotNull
                             java.lang.String baseDN,
                             @NotNull
                             SearchScope scope,
                             @NotNull
                             Filter filter,
                             @Nullable
                             java.lang.String... attributes)
        Creates a new search request with the provided information. Search result entries and references will be collected internally and included in the SearchResult object returned when search processing is completed.
        Parameters:
        baseDN - The base DN for the search request. It must not be null.
        scope - The scope that specifies the range of entries that should be examined for the search.
        filter - The string representation of the filter to use to identify matching entries. It must not be null.
        attributes - The set of attributes that should be returned in matching entries. It may be null or empty if the default attribute set (all user attributes) is to be requested.
      • SearchRequest

        public SearchRequest​(@Nullable
                             SearchResultListener searchResultListener,
                             @NotNull
                             java.lang.String baseDN,
                             @NotNull
                             SearchScope scope,
                             @NotNull
                             java.lang.String filter,
                             @Nullable
                             java.lang.String... attributes)
                      throws LDAPException
        Creates a new search request with the provided information.
        Parameters:
        searchResultListener - The search result listener that should be used to return results to the client. It may be null if the search results should be collected internally and returned in the SearchResult object.
        baseDN - The base DN for the search request. It must not be null.
        scope - The scope that specifies the range of entries that should be examined for the search.
        filter - The string representation of the filter to use to identify matching entries. It must not be null.
        attributes - The set of attributes that should be returned in matching entries. It may be null or empty if the default attribute set (all user attributes) is to be requested.
        Throws:
        LDAPException - If the provided filter string cannot be parsed as an LDAP filter.
      • SearchRequest

        public SearchRequest​(@Nullable
                             SearchResultListener searchResultListener,
                             @NotNull
                             java.lang.String baseDN,
                             @NotNull
                             SearchScope scope,
                             @NotNull
                             Filter filter,
                             @Nullable
                             java.lang.String... attributes)
        Creates a new search request with the provided information.
        Parameters:
        searchResultListener - The search result listener that should be used to return results to the client. It may be null if the search results should be collected internally and returned in the SearchResult object.
        baseDN - The base DN for the search request. It must not be null.
        scope - The scope that specifies the range of entries that should be examined for the search.
        filter - The string representation of the filter to use to identify matching entries. It must not be null.
        attributes - The set of attributes that should be returned in matching entries. It may be null or empty if the default attribute set (all user attributes) is to be requested.
      • SearchRequest

        public SearchRequest​(@NotNull
                             java.lang.String baseDN,
                             @NotNull
                             SearchScope scope,
                             @NotNull
                             DereferencePolicy derefPolicy,
                             int sizeLimit,
                             int timeLimit,
                             boolean typesOnly,
                             @NotNull
                             java.lang.String filter,
                             @Nullable
                             java.lang.String... attributes)
                      throws LDAPException
        Creates a new search request with the provided information. Search result entries and references will be collected internally and included in the SearchResult object returned when search processing is completed.
        Parameters:
        baseDN - The base DN for the search request. It must not be null.
        scope - The scope that specifies the range of entries that should be examined for the search.
        derefPolicy - The dereference policy the server should use for any aliases encountered while processing the search.
        sizeLimit - The maximum number of entries that the server should return for the search. A value of zero indicates that there should be no limit.
        timeLimit - The maximum length of time in seconds that the server should spend processing this search request. A value of zero indicates that there should be no limit.
        typesOnly - Indicates whether to return only attribute names in matching entries, or both attribute names and values.
        filter - The filter to use to identify matching entries. It must not be null.
        attributes - The set of attributes that should be returned in matching entries. It may be null or empty if the default attribute set (all user attributes) is to be requested.
        Throws:
        LDAPException - If the provided filter string cannot be parsed as an LDAP filter.
      • SearchRequest

        public SearchRequest​(@NotNull
                             java.lang.String baseDN,
                             @NotNull
                             SearchScope scope,
                             @NotNull
                             DereferencePolicy derefPolicy,
                             int sizeLimit,
                             int timeLimit,
                             boolean typesOnly,
                             @NotNull
                             Filter filter,
                             @Nullable
                             java.lang.String... attributes)
        Creates a new search request with the provided information. Search result entries and references will be collected internally and included in the SearchResult object returned when search processing is completed.
        Parameters:
        baseDN - The base DN for the search request. It must not be null.
        scope - The scope that specifies the range of entries that should be examined for the search.
        derefPolicy - The dereference policy the server should use for any aliases encountered while processing the search.
        sizeLimit - The maximum number of entries that the server should return for the search. A value of zero indicates that there should be no limit.
        timeLimit - The maximum length of time in seconds that the server should spend processing this search request. A value of zero indicates that there should be no limit.
        typesOnly - Indicates whether to return only attribute names in matching entries, or both attribute names and values.
        filter - The filter to use to identify matching entries. It must not be null.
        attributes - The set of attributes that should be returned in matching entries. It may be null or empty if the default attribute set (all user attributes) is to be requested.
      • SearchRequest

        public SearchRequest​(@Nullable
                             SearchResultListener searchResultListener,
                             @NotNull
                             java.lang.String baseDN,
                             @NotNull
                             SearchScope scope,
                             @NotNull
                             DereferencePolicy derefPolicy,
                             int sizeLimit,
                             int timeLimit,
                             boolean typesOnly,
                             @NotNull
                             java.lang.String filter,
                             @Nullable
                             java.lang.String... attributes)
                      throws LDAPException
        Creates a new search request with the provided information.
        Parameters:
        searchResultListener - The search result listener that should be used to return results to the client. It may be null if the search results should be collected internally and returned in the SearchResult object.
        baseDN - The base DN for the search request. It must not be null.
        scope - The scope that specifies the range of entries that should be examined for the search.
        derefPolicy - The dereference policy the server should use for any aliases encountered while processing the search.
        sizeLimit - The maximum number of entries that the server should return for the search. A value of zero indicates that there should be no limit.
        timeLimit - The maximum length of time in seconds that the server should spend processing this search request. A value of zero indicates that there should be no limit.
        typesOnly - Indicates whether to return only attribute names in matching entries, or both attribute names and values.
        filter - The filter to use to identify matching entries. It must not be null.
        attributes - The set of attributes that should be returned in matching entries. It may be null or empty if the default attribute set (all user attributes) is to be requested.
        Throws:
        LDAPException - If the provided filter string cannot be parsed as an LDAP filter.
      • SearchRequest

        public SearchRequest​(@Nullable
                             SearchResultListener searchResultListener,
                             @NotNull
                             java.lang.String baseDN,
                             @NotNull
                             SearchScope scope,
                             @NotNull
                             DereferencePolicy derefPolicy,
                             int sizeLimit,
                             int timeLimit,
                             boolean typesOnly,
                             @NotNull
                             Filter filter,
                             @Nullable
                             java.lang.String... attributes)
        Creates a new search request with the provided information.
        Parameters:
        searchResultListener - The search result listener that should be used to return results to the client. It may be null if the search results should be collected internally and returned in the SearchResult object.
        baseDN - The base DN for the search request. It must not be null.
        scope - The scope that specifies the range of entries that should be examined for the search.
        derefPolicy - The dereference policy the server should use for any aliases encountered while processing the search.
        sizeLimit - The maximum number of entries that the server should return for the search. A value of zero indicates that there should be no limit.
        timeLimit - The maximum length of time in seconds that the server should spend processing this search request. A value of zero indicates that there should be no limit.
        typesOnly - Indicates whether to return only attribute names in matching entries, or both attribute names and values.
        filter - The filter to use to identify matching entries. It must not be null.
        attributes - The set of attributes that should be returned in matching entries. It may be null or empty if the default attribute set (all user attributes) is to be requested.
      • SearchRequest

        public SearchRequest​(@Nullable
                             SearchResultListener searchResultListener,
                             @Nullable
                             Control[] controls,
                             @NotNull
                             java.lang.String baseDN,
                             @NotNull
                             SearchScope scope,
                             @NotNull
                             DereferencePolicy derefPolicy,
                             int sizeLimit,
                             int timeLimit,
                             boolean typesOnly,
                             @NotNull
                             java.lang.String filter,
                             @Nullable
                             java.lang.String... attributes)
                      throws LDAPException
        Creates a new search request with the provided information.
        Parameters:
        searchResultListener - The search result listener that should be used to return results to the client. It may be null if the search results should be collected internally and returned in the SearchResult object.
        controls - The set of controls to include in the request. It may be null or empty if no controls should be included in the request.
        baseDN - The base DN for the search request. It must not be null.
        scope - The scope that specifies the range of entries that should be examined for the search.
        derefPolicy - The dereference policy the server should use for any aliases encountered while processing the search.
        sizeLimit - The maximum number of entries that the server should return for the search. A value of zero indicates that there should be no limit.
        timeLimit - The maximum length of time in seconds that the server should spend processing this search request. A value of zero indicates that there should be no limit.
        typesOnly - Indicates whether to return only attribute names in matching entries, or both attribute names and values.
        filter - The filter to use to identify matching entries. It must not be null.
        attributes - The set of attributes that should be returned in matching entries. It may be null or empty if the default attribute set (all user attributes) is to be requested.
        Throws:
        LDAPException - If the provided filter string cannot be parsed as an LDAP filter.
      • SearchRequest

        public SearchRequest​(@Nullable
                             SearchResultListener searchResultListener,
                             @Nullable
                             Control[] controls,
                             @NotNull
                             java.lang.String baseDN,
                             @NotNull
                             SearchScope scope,
                             @NotNull
                             DereferencePolicy derefPolicy,
                             int sizeLimit,
                             int timeLimit,
                             boolean typesOnly,
                             @NotNull
                             Filter filter,
                             @Nullable
                             java.lang.String... attributes)
        Creates a new search request with the provided information.
        Parameters:
        searchResultListener - The search result listener that should be used to return results to the client. It may be null if the search results should be collected internally and returned in the SearchResult object.
        controls - The set of controls to include in the request. It may be null or empty if no controls should be included in the request.
        baseDN - The base DN for the search request. It must not be null.
        scope - The scope that specifies the range of entries that should be examined for the search.
        derefPolicy - The dereference policy the server should use for any aliases encountered while processing the search.
        sizeLimit - The maximum number of entries that the server should return for the search. A value of zero indicates that there should be no limit.
        timeLimit - The maximum length of time in seconds that the server should spend processing this search request. A value of zero indicates that there should be no limit.
        typesOnly - Indicates whether to return only attribute names in matching entries, or both attribute names and values.
        filter - The filter to use to identify matching entries. It must not be null.
        attributes - The set of attributes that should be returned in matching entries. It may be null or empty if the default attribute set (all user attributes) is to be requested.
    • Method Detail

      • setBaseDN

        public void setBaseDN​(@NotNull
                              java.lang.String baseDN)
        Specifies the base DN for this search request.
        Parameters:
        baseDN - The base DN for this search request. It must not be null.
      • setBaseDN

        public void setBaseDN​(@NotNull
                              DN baseDN)
        Specifies the base DN for this search request.
        Parameters:
        baseDN - The base DN for this search request. It must not be null.
      • setScope

        public void setScope​(@NotNull
                             SearchScope scope)
        Specifies the scope for this search request.
        Parameters:
        scope - The scope for this search request.
      • setDerefPolicy

        public void setDerefPolicy​(@NotNull
                                   DereferencePolicy derefPolicy)
        Specifies the dereference policy that should be used by the server for any aliases encountered during search processing.
        Parameters:
        derefPolicy - The dereference policy that should be used by the server for any aliases encountered during search processing.
      • getSizeLimit

        public int getSizeLimit()
        Retrieves the maximum number of entries that should be returned by the server when processing this search request.
        Specified by:
        getSizeLimit in interface ReadOnlySearchRequest
        Returns:
        The maximum number of entries that should be returned by the server when processing this search request, or zero if there is no limit.
      • setSizeLimit

        public void setSizeLimit​(int sizeLimit)
        Specifies the maximum number of entries that should be returned by the server when processing this search request. A value of zero indicates that there should be no limit.

        Note that if an attempt to process a search operation fails because the size limit has been exceeded, an LDAPSearchException will be thrown. If one or more entries or references have already been returned for the search, then the LDAPSearchException methods like getEntryCount, getSearchEntries, getReferenceCount, and getSearchReferences may be used to obtain information about those entries and references (although if a search result listener was provided, then it will have been used to make any entries and references available, and they will not be available through the getSearchEntries and getSearchReferences methods).
        Parameters:
        sizeLimit - The maximum number of entries that should be returned by the server when processing this search request.
      • getTimeLimitSeconds

        public int getTimeLimitSeconds()
        Retrieves the maximum length of time in seconds that the server should spend processing this search request.
        Specified by:
        getTimeLimitSeconds in interface ReadOnlySearchRequest
        Returns:
        The maximum length of time in seconds that the server should spend processing this search request, or zero if there is no limit.
      • setTimeLimitSeconds

        public void setTimeLimitSeconds​(int timeLimit)
        Specifies the maximum length of time in seconds that the server should spend processing this search request. A value of zero indicates that there should be no limit.

        Note that if an attempt to process a search operation fails because the time limit has been exceeded, an LDAPSearchException will be thrown. If one or more entries or references have already been returned for the search, then the LDAPSearchException methods like getEntryCount, getSearchEntries, getReferenceCount, and getSearchReferences may be used to obtain information about those entries and references (although if a search result listener was provided, then it will have been used to make any entries and references available, and they will not be available through the getSearchEntries and getSearchReferences methods).
        Parameters:
        timeLimit - The maximum length of time in seconds that the server should spend processing this search request.
      • typesOnly

        public boolean typesOnly()
        Indicates whether the server should return only attribute names in matching entries, rather than both names and values.
        Specified by:
        typesOnly in interface ReadOnlySearchRequest
        Returns:
        true if matching entries should include only attribute names, or false if matching entries should include both attribute names and values.
      • setTypesOnly

        public void setTypesOnly​(boolean typesOnly)
        Specifies whether the server should return only attribute names in matching entries, rather than both names and values.
        Parameters:
        typesOnly - Specifies whether the server should return only attribute names in matching entries, rather than both names and values.
      • setFilter

        public void setFilter​(@NotNull
                              java.lang.String filter)
                       throws LDAPException
        Specifies the filter that should be used to identify matching entries.
        Parameters:
        filter - The string representation for the filter that should be used to identify matching entries. It must not be null.
        Throws:
        LDAPException - If the provided filter string cannot be parsed as a search filter.
      • setFilter

        public void setFilter​(@NotNull
                              Filter filter)
        Specifies the filter that should be used to identify matching entries.
        Parameters:
        filter - The filter that should be used to identify matching entries. It must not be null.
      • getAttributes

        @NotNull
        public java.lang.String[] getAttributes()
        Retrieves the set of requested attributes to include in matching entries. The caller must not attempt to alter the contents of the array.
        Returns:
        The set of requested attributes to include in matching entries, or an empty array if the default set of attributes (all user attributes but no operational attributes) should be requested.
      • getAttributeList

        @NotNull
        public java.util.List<java.lang.String> getAttributeList()
        Retrieves the set of requested attributes to include in matching entries.
        Specified by:
        getAttributeList in interface ReadOnlySearchRequest
        Returns:
        The set of requested attributes to include in matching entries, or an empty array if the default set of attributes (all user attributes but no operational attributes) should be requested.
      • setAttributes

        public void setAttributes​(@Nullable
                                  java.lang.String... attributes)
        Specifies the set of requested attributes to include in matching entries.
        Parameters:
        attributes - The set of requested attributes to include in matching entries. It may be null if the default set of attributes (all user attributes but no operational attributes) should be requested.
      • setAttributes

        public void setAttributes​(@Nullable
                                  java.util.List<java.lang.String> attributes)
        Specifies the set of requested attributes to include in matching entries.
        Parameters:
        attributes - The set of requested attributes to include in matching entries. It may be null if the default set of attributes (all user attributes but no operational attributes) should be requested.
      • getSearchResultListener

        @Nullable
        public SearchResultListener getSearchResultListener()
        Retrieves the search result listener for this search request, if available.
        Returns:
        The search result listener for this search request, or null if none has been configured.
      • writeTo

        public void writeTo​(@NotNull
                            ASN1Buffer writer)
        Writes an ASN.1-encoded representation of this LDAP protocol op to the provided ASN.1 buffer. This method is intended for internal use only and should not be used by third-party code.
        Specified by:
        writeTo in interface ProtocolOp
        Parameters:
        writer - The ASN.1 buffer to which the encoded representation should be written.
      • process

        @NotNull
        protected SearchResult process​(@NotNull
                                       LDAPConnection connection,
                                       int depth)
                                throws LDAPException
        Sends this search request to the directory server over the provided connection and returns the associated response. The search result entries and references will either be collected and returned in the SearchResult object that is returned, or will be interactively returned via the SearchResultListener interface.
        Specified by:
        process in class LDAPRequest
        Parameters:
        connection - The connection to use to communicate with the directory server.
        depth - The current referral depth for this request. It should always be one for the initial request, and should only be incremented when following referrals.
        Returns:
        An object that provides information about the result of the search processing, potentially including the sets of matching entries and/or search references.
        Throws:
        LDAPException - If a problem occurs while sending the request or reading the response.
      • getLastMessageID

        public int getLastMessageID()
        Retrieves the message ID for the last LDAP message sent using this request.
        Specified by:
        getLastMessageID in class LDAPRequest
        Returns:
        The message ID for the last LDAP message sent using this request, or -1 if it no LDAP messages have yet been sent using this request.
      • duplicate

        @NotNull
        public SearchRequest duplicate​(@Nullable
                                       Control[] controls)
        Creates a new instance of this LDAP request that may be modified without impacting this request. The provided controls will be used for the new request instead of duplicating the controls from this request.
        Specified by:
        duplicate in interface ReadOnlyLDAPRequest
        Specified by:
        duplicate in interface ReadOnlySearchRequest
        Parameters:
        controls - The set of controls to include in the duplicate request.
        Returns:
        A new instance of this LDAP request that may be modified without impacting this request.
      • toCode

        public void toCode​(@NotNull
                           java.util.List<java.lang.String> lineList,
                           @NotNull
                           java.lang.String requestID,
                           int indentSpaces,
                           boolean includeProcessing)
        Appends a number of lines comprising the Java source code that can be used to recreate this request to the given list.
        Specified by:
        toCode in interface ReadOnlyLDAPRequest
        Parameters:
        lineList - The list to which the source code lines should be added.
        requestID - The name that should be used as an identifier for the request. If this is null or empty, then a generic ID will be used.
        indentSpaces - The number of spaces that should be used to indent the generated code. It must not be negative.
        includeProcessing - Indicates whether the generated code should include code required to actually process the request and handle the result (if true), or just to generate the request (if false).