OPENICF-329 Align the OpenICF Filter and CREST QueryFilter

Author: Laszlo Hordos

Framework/CommonObjects.cs

@@ -2993,6 +2993,12 @@ public sealed class OperationOptions
         /// </summary>
         public static readonly string OP_PAGED_RESULTS_COOKIE = "PAGED_RESULTS_COOKIE";
 
+        /// <summary>
+        /// An option to use with <seealso cref="SearchApiOp"/> that specifies the policy used for calculating
+        /// the total number of paged results.
+        /// </summary>
+        public const string OP_TOTAL_PAGED_RESULTS_POLICY = "TOTAL_PAGED_RESULTS_POLICY";
+
         /// <summary>
         /// An option to use with <seealso cref="SearchApiOp"/> that specifies the index within
         /// the result set of the first result which should be returned.
@@ -3137,6 +3143,22 @@ public string PagedResultsCookie
             }
         }
 
+        /// <summary>
+        /// Returns the <seealso cref="SearchResult.CountPolicy"/> used to calculate
+        /// <seealso cref="SearchResult#getTotalPagedResults()"/>.
+        /// </summary>
+        /// <returns> The count policy. </returns>
+        /// <seealso cref= SearchResult#getTotalPagedResults()</seealso>
+        /// <remarks>Since 1.5</remarks>
+        public SearchResult.CountPolicy TotalPagedResultsPolicy
+        {
+            get
+            {
+                return (SearchResult.CountPolicy)CollectionUtil.GetValue(
+                        _operationOptions, OP_TOTAL_PAGED_RESULTS_POLICY, SearchResult.CountPolicy.NONE);
+            }
+        }
+
         /// <summary>
         /// Returns the index within the result set of the first result which should
         /// be returned. Paged results will be enabled if and only if the page size
@@ -3372,6 +3394,22 @@ public string PagedResultsCookie
             }
         }
 
+        /// <summary>
+        /// Sets the policy for calculating the total number of paged results. If no
+        /// count policy is supplied or paged results are not requested a default of
+        /// <seealso cref="SearchResult.CountPolicy#NONE"/> will be used. This will result in no count being
+        /// performed and no overhead incurred.
+        /// </summary>
+        /// <remarks>Since 1.5</remarks>
+        public SearchResult.CountPolicy TotalPagedResultsPolicy
+        {
+            set
+            {
+                Assertions.NullCheck(value, "totalPagedResultsPolicy");
+                _options[OperationOptions.OP_TOTAL_PAGED_RESULTS_POLICY] = value;
+            }
+        }
+
         /// <summary>
         /// Convenience method to set
         /// <seealso cref="OperationOptions#OP_PAGED_RESULTS_OFFSET"/>
@@ -4834,15 +4872,48 @@ public ScriptContext Build()
     public sealed class SearchResult
     {
 
+        /// <summary>
+        /// An enum of count policy types.
+        /// </summary>
+        /// <seealso cref= OperationOptionsBuilder#setTotalPagedResultsPolicy(CountPolicy) </seealso>
+        /// <seealso cref= SearchResult#getTotalPagedResultsPolicy() </seealso>
+        public enum CountPolicy
+        {
+            /// <summary>
+            /// There should be no count returned. No overhead should be incurred.
+            /// </summary>
+            NONE,
+
+            /// <summary>
+            /// Estimated count may be used. If no estimation is available it is up
+            /// to the implementor whether to return an <seealso cref="#EXACT"/> count or
+            /// <seealso cref="#NONE"/>. It should be known to the client which was used as in
+            /// <seealso cref="SearchResult#getTotalPagedResultsPolicy()"/>
+            /// </summary>
+            ESTIMATE,
+
+            /// <summary>
+            /// Exact count is required.
+            /// </summary>
+            EXACT
+        }
+
+        /// <summary>
+        /// The value provided when no count is known or can reasonably be supplied.
+        /// </summary>
+        public const int NoCount = -1;
+
         private readonly string _pagedResultsCookie;
+        private readonly CountPolicy _totalPagedResultsPolicy;
+        private readonly int _totalPagedResults;
         private readonly int _remainingPagedResults;
 
         /// <summary>
         /// Creates a new search result with a {@code null} paged results cookie and
         /// no estimate of the total number of remaining results.
         /// </summary>
         public SearchResult()
-            : this(null, -1)
+            : this(null, CountPolicy.NONE, NoCount, NoCount)
         {
         }
 
@@ -4860,9 +4931,41 @@ public SearchResult()
         ///            {@code -1} if paged results were not requested, or if the
         ///            total number of remaining results is unknown. </param>
         public SearchResult(string pagedResultsCookie, int remainingPagedResults)
+            : this(pagedResultsCookie, CountPolicy.NONE, NoCount, remainingPagedResults)
         {
-            this._pagedResultsCookie = pagedResultsCookie;
-            this._remainingPagedResults = remainingPagedResults;
+        }
+
+        /// <summary>
+        /// Creates a new query response with the provided paged results cookie and a
+        /// count of the total number of resources according to
+        /// <seealso cref="#totalPagedResultsPolicy"/>.
+        /// </summary>
+        /// <param name="pagedResultsCookie">
+        ///            The opaque cookie which should be used with the next paged
+        ///            results query request, or {@code null} if paged results were
+        ///            not requested, or if there are not more pages to be returned. </param>
+        /// <param name="totalPagedResultsPolicy">
+        ///            The policy that was used to calculate
+        ///            <seealso cref="#totalPagedResults"/>. If none is specified ({@code null}
+        ///            ), then <seealso cref="CountPolicy#NONE"/> is assumed. </param>
+        /// <param name="totalPagedResults">
+        ///            The total number of paged results requested in adherence to
+        ///            the <seealso cref="OperationOptions#getTotalPagedResultsPolicy()"/> in
+        ///            the request, or <seealso cref="#NO_COUNT"/> if paged results were not
+        ///            requested, the count policy is {@code NONE}, or if the total
+        ///            number of results is unknown. </param>
+        /// <param name="remainingPagedResults">
+        ///            An estimate of the total number of remaining results to be
+        ///            returned in subsequent paged results query requests, or
+        ///            {@code -1} if paged results were not requested, or if the
+        ///            total number of remaining results is unknown.</param>
+        /// <remarks>Since 1.5</remarks>
+        public SearchResult(string pagedResultsCookie, CountPolicy totalPagedResultsPolicy, int totalPagedResults, int remainingPagedResults)
+        {
+            _pagedResultsCookie = pagedResultsCookie;
+            _totalPagedResultsPolicy = totalPagedResultsPolicy;
+            _totalPagedResults = totalPagedResults;
+            _remainingPagedResults = remainingPagedResults;
         }
 
         /// <summary>
@@ -4880,6 +4983,39 @@ public string PagedResultsCookie
             }
         }
 
+        /// <summary>
+        /// Returns the policy that was used to calculate the
+        /// {@literal totalPagedResults}.
+        /// </summary>
+        /// <returns> The count policy. </returns></seealso>
+        /// <remarks>Since 1.5</remarks>
+        public CountPolicy TotalPagedResultsPolicy
+        {
+            get
+            {
+                return _totalPagedResultsPolicy;
+            }
+        }
+
+        /// <summary>
+        /// Returns the total number of paged results in adherence with the
+        /// <seealso cref="OperationOptions#getTotalPagedResultsPolicy()"/> in the request or
+        /// <seealso cref="#NO_COUNT"/> if paged results were not requested, the count policy
+        /// is {@code NONE}, or the total number of paged results is unknown.
+        /// </summary>
+        /// <returns> A count of the total number of paged results to be returned in
+        ///         subsequent paged results query requests, or <seealso cref="#NO_COUNT"/> if
+        ///         paged results were not requested, or if the total number of paged
+        ///         results is unknown. </returns>
+        /// <remarks>Since 1.5</remarks>
+        public int TotalPagedResults
+        {
+            get
+            {
+                return _totalPagedResults;
+            }
+        }
+
         /// <summary>
         /// Returns an estimate of the total number of remaining results to be
         /// returned in subsequent paged results search requests.

Framework/CommonObjectsFilter.cs

@@ -1104,6 +1104,50 @@ public override string ToString()
     }
     #endregion
 
+    #region ExtendedMatchFilter
+    public sealed class ExtendedMatchFilter : AttributeFilter
+    {
+
+        /// <summary>
+        /// Creates a new {@code extended match} filter using the provided operator
+        /// and attribute assertion.
+        /// </summary>
+        /// <param name="operator">
+        ///            The operator. </param>
+        /// <param name="attribute">
+        ///            The assertion value. </param>
+        public ExtendedMatchFilter(string @operator, ConnectorAttribute attribute)
+            : base(attribute)
+        {
+            if (StringUtil.IsBlank(@operator))
+            {
+                throw new ArgumentException("Operator not be null!");
+            }
+            Operator = @operator;
+        }
+
+        public string Operator
+        {
+            get;
+            internal set;
+        }
+
+        /// <summary>
+        /// Framework can not understand this filter, always return true.
+        /// <seealso cref="ConnectorObject"/>.
+        /// </summary>
+        public override bool Accept(ConnectorObject obj)
+        {
+            return true;
+        }
+
+        public override TR Accept<TR, TP>(FilterVisitor<TR, TP> v, TP p)
+        {
+            return v.VisitExtendedFilter(p, this);
+        }
+    }
+    #endregion
+
     #region Filter
     public interface Filter
     {
@@ -1415,6 +1459,20 @@ public static Filter EqualTo(ConnectorAttribute attr)
             return new EqualsFilter(attr);
         }
 
+        /// <summary>
+        /// Creates a new {@code extended match} filter using the provided operator
+        /// and attribute assertion.
+        /// </summary>
+        /// <param name="operator">
+        ///            The operator. </param>
+        /// <param name="attribute">
+        ///            The assertion value.</param>
+        /// <remarks>Since 1.5</remarks>
+        public static Filter ExtendedMatch(string @operator, ConnectorAttribute attribute)
+        {
+            return new ExtendedMatchFilter(@operator, attribute);
+        }
+
         /// <summary>
         /// Ands the two <see cref="Filter" />.
         /// </summary>
@@ -1502,6 +1560,7 @@ public static Filter Not(Filter filter)
         ///            The name of field within the <seealso cref="Org.IdentityConnectors.Framework.Common.Objects.ConnectorObject"/> which must be
         ///            present. </param>
         /// <returns> The newly created {@code presence} filter. </returns>
+        /// <remarks>Since 1.5</remarks>
         public static Filter Present(string attributeName)
         {
             return new PresenceFilter(attributeName);

FrameworkInternal/Resources.resx

@@ -119,7 +119,6 @@
   </resheader>
   <data name="connectors.dtd" xml:space="preserve">
     <value>&lt;?xml version='1.0' encoding='UTF-8'?&gt;
-
 &lt;!--=======================================================--&gt;
 &lt;!--=                                                     =--&gt;
 &lt;!--= DTD for Connector Objects                           =--&gt;
@@ -149,9 +148,9 @@
   "&gt;
 
 &lt;!ENTITY % filterTypes
-  "AndFilter | ContainsFilter | EndsWithFilter | EqualsFilter |
+  "AndFilter | ContainsFilter | EndsWithFilter | EqualsFilter | ExtendedMatchFilter |
   GreaterThanFilter | GreaterThanOrEqualFilter | LessThanFilter |
-  LessThanOrEqualFilter | NotFilter | OrFilter | StartsWithFilter |
+  LessThanOrEqualFilter | NotFilter | OrFilter | PresenceFilter | StartsWithFilter |
   ContainsAllValuesFilter
   "&gt;
 
@@ -172,7 +171,7 @@ ObjectPoolConfiguration | ResultsHandlerConfiguration | ConfigurationProperty |
 APIConfiguration | ConnectorMessages | ConnectorKey | ConnectorInfo |
 UpdateApiOpType | AttributeInfo | ConnectorObject | ObjectClass |
 ObjectClassInfo | Schema | Script | ScriptContext | OperationOptions |
-OperationOptionInfo | SyncDeltaType | SyncToken | SyncDelta | QualifiedUid
+OperationOptionInfo | SearchResult | SyncDeltaType | SyncToken | SyncDelta | QualifiedUid
 "&gt;
 
 
@@ -486,6 +485,16 @@ OperationOptionInfo | SyncDeltaType | SyncToken | SyncDelta | QualifiedUid
 
 &lt;!ELEMENT QualifiedUid (ObjectClass,Uid)&gt;
 
+&lt;!ELEMENT CountPolicy EMPTY&gt;
+&lt;!ATTLIST CountPolicy
+   value ( NONE | ESTIMATE | EXACT ) #REQUIRED
+&gt;
+&lt;!ELEMENT SearchResult (CountPolicy?)&gt;
+&lt;!ATTLIST SearchResult
+   pagedResultsCookie CDATA #REQUIRED
+   remainingPagedResults CDATA #REQUIRED
+   totalPagedResults CDATA #REQUIRED
+&gt;
 
 &lt;!--=======================================================--&gt;
 &lt;!--=                                                     =--&gt;
@@ -499,12 +508,20 @@ OperationOptionInfo | SyncDeltaType | SyncToken | SyncDelta | QualifiedUid
 &lt;!ELEMENT ContainsFilter (attribute)&gt;
 &lt;!ELEMENT EndsWithFilter (attribute)&gt;
 &lt;!ELEMENT EqualsFilter (attribute)&gt;
+&lt;!ELEMENT ExtendedMatchFilter (attribute)&gt;
+&lt;!ATTLIST ExtendedMatchFilter
+   operator CDATA #IMPLIED
+&gt;
 &lt;!ELEMENT GreaterThanFilter (attribute)&gt;
 &lt;!ELEMENT GreaterThanOrEqualFilter (attribute)&gt;
 &lt;!ELEMENT LessThanFilter (attribute)&gt;
 &lt;!ELEMENT LessThanOrEqualFilter (attribute)&gt;
 &lt;!ELEMENT NotFilter (%filterTypes;)&gt;
 &lt;!ELEMENT OrFilter ((%filterTypes;),(%filterTypes;))&gt;
+&lt;!ELEMENT PresenceFilter (#PCDATA)&gt;
+&lt;!ATTLIST PresenceFilter
+   name CDATA #IMPLIED
+&gt;
 &lt;!ELEMENT StartsWithFilter (attribute)&gt;
 &lt;!ELEMENT ContainsAllValuesFilter (attribute)&gt;