Package com.documentum.fc.client.search

Class DfFacetDefinition

java.lang.Object
com.documentum.fc.client.search.DfFacetDefinition
public final class DfFacetDefinition extends Object
This class define a facet to be computed by the search service.

A facet is a mechanism to group results according to some values that are shared by the results. Facet can be used to group results by author, date...

A facet definition defines how facets values will be returned.

A facet definition accepts different grouping strategies:

  • string
  • day, week, month, quarter, year, relativeDate
  • range
  • alpharange
See Also:

  • Constructor Details

    • DfFacetDefinition

      public DfFacetDefinition(String name)
      Create a new definition.
      Parameters:
      name - name for the facet. Example: author

  • Method Details

    • getName

      public String getName()
      Get the name for the facet
      Returns:
      example: author

    • setName

      public void setName(String name)
      Set the name for the facet
      Parameters:
      name - name for the facet. Example: author

    • getGroupBy

      public String getGroupBy()
      Get the grouping startegy used for this facet.
      See Also:

    • setGroupBy

      public void setGroupBy(String groupBy)
      Set the grouping used to compute facets.

      The grouping used may depend on the datatype of the attributes to be used to compute facets.

      The available grouping strategies are:

      • string
      • The following grouping strategies applies only to dates. An optional property 'timezone' allows to specify the client timezone (Ex.: 'GMT+1')
        • day
        • week
        • month
        • quarter (since xPlore 1.3)
        • year
        • relativeDate

        The facet values returned will be the start date of the range, using UTC timezone.

        Example: for january 2011, the facet value will be 2001-01-01T00:00:00 (this time will be adjusted if the property 'timezone' is specified).

      • range - applies to numeric values. Range grouping require a property 'range' that defines the ranges to use for grouping. Example: '0:1000,1000:10000,10000:'.
      • location - used for CIS entities
      • alpharange - applies to string values (since xPlore 1.3). Range grouping requires a property 'range' that defines the ranges to use for grouping. Example: 'a:m,n:r,s:z'. This grouping strategy uses unicode order, not language dependent order (see java.text.Collator for more background).

        In practice, it is only useful for ascii character.

      By default, 'string' will be used.

      Parameters:
      groupBy - the name of the grouping strategy
      See Also:

    • getOrderBy

      public DfFacetDefinition.ORDER getOrderBy()
      Get the sorting order used for facet values returned.

    • setOrderBy

      public void setOrderBy(DfFacetDefinition.ORDER orderBy)
      Set the sorting order used for facet values returned.

      If no sorting order is set, the facet values will be sorted by frequency or by value ascending if max is set to -1.

      Which sort order to pick depends on the grouping strategy used and the application use case. Typically a 'relativeDate' and 'range' grouping will need to be sorted using 'NONE' while a 'string' grouping would be sorted by frequency.

    • addAttribute

      public void addAttribute(String attr)
      Add an attribute to use for facet computation. By default, the name is used for attribute.

    • setAttributes

      public void setAttributes(Collection<String> attrs)
      Set the list of attributes to use for facet computation. In most case there will be only one.

    • getAttributes

      public List<String> getAttributes()
      Get the list of attributes used for facet computation. If it is empty, the facet definition name is used.

    • hasMax

      public boolean hasMax()
      Indicate if the definition specified a maximum number of facets
      Returns:
      true if a max has been set

    • getMax

      public Integer getMax()
      Get the maximum number of facet. May return null if none has been set
      Returns:
      Maximum number of facets values

    • setMax

      public void setMax(Integer max)
      Set the maximum number of facets value.
      Parameters:
      max - -1 to get all the values. If nothing is specified, the maximum is 10.

    • setProperty

      public void setProperty(String name, String value)
      Set a custom property to be used for certain grouping strategy. Custom property are ignored if they are not supported by the facet handler.

      The date grouping accept the following parameter:

      • timezone (optional): a timezone code. Default: Z (UTC). The timezone to be used to compute date grouping.
      • returnUTC (optional) - since xPlore 1.3: a boolean. Default: 'false'. If timezone is specified, the dates in the facets will be returned formatted in this timezone. The same timezone is used to compute the date range boundaries and to format the facets. If returnUTC is set to 'true', the date in the facet will be formatted in UTC (timezone will only be used for computation, not for formatting)
      • skipEmptyValues (optional): a boolean. Default: false. If skipEmptyValues is set to 'true', only the facet values with a count strictly greater than zero are returned. If skipEmptyValues is set to 'false', the query will return all the facet values between the oldest non-zero facet value and the most recent non-zero facet values.

      The 'range' and 'alpharange' grouping requires the following parameter:

      • range (required). This property defines a list of 'buckets' to use for grouping. Each bucket is separated by comma (','). A bucket is defined by a lower and upper bounds separated by colon (':'). Open ended bucket can be defined by omitting one of the bounds but keeping the comma separator. Overlapping buckets are not supported and may result in inconsistent results.

        For 'range':

        • The boundaries themselves are parsed as Double.

          Example: '0:10,10:100.89,100:'

        • The lower-bound is inclusive. The upper-bound is exclusive. For example, for a facet value corresponding to '0:1000', the constraint should be (attribute >= 0 and attribute <1000).
        For 'alpharange':
        • The boundaries are parsed as one character.

          Example: 'a:m,n:r,s:z'

        • This grouping strategy is case-insensitive. Special care must be taken when adding a constraint based on such a facet value because the comparison operators on string (<, <=, >=, >) are case sensitive. As a consequence, one has to add 2 constraints: one on the lower-case range and one on the upper-case range.
        • The upper-bound and lower-bound are returned as a property of the facet value. The boundaries are inclusive. As a consequence, the constraint on the upper-bound should add 1 to the actual character.

          Example: for a facet value corresponding to 'a-m', the constraint should be (attribute >= 'a' and attribute < 'n') or (attribute >='A' and attribute < 'N')

      The default grouping strategy (string) accept the following parameter:

      • nullValueFacet (optional): if this property is set, null values will be counted as a facet. The facet will be named using the value of the property. By default, the null values are ignored when computing facets
      • keepDuplicateValues (optional): true/false. Default: false. For a document, attributes with repeating values may have duplicate values. By default, duplicates are removed. If this property is set to true, duplicates entries are counted. Since: xPlore 1.1 P03 and 1.2
      • caseInsensitive (optional): true/false. Default: false. If this property is set to true, facet computation ignore case. For example, if a results set has a document with a value 'emc' and another 'EMC', two facets will be returned, emc(1) and EMC(1). Since: xPlore 1.1 P03 and 1.2
      Parameters:
      name - property's name
      value - property's value. This is a String representation. Depending on the property name it may be parsed as a boolean or a numerical value.

    • getProperty

      public String getProperty(String name)

    • getProperties

      public Map<String,String> getProperties()

    • setSubFacetDefinition

      public void setSubFacetDefinition(DfFacetDefinition definition)
      Define a facet definition to be used to compute sub-facets some 'grouping' strategy do not support sub-facets: 'relativeDate' and 'location'.
      Parameters:
      definition - a DfFacetDefinition. The definition can be nested recursively.

    • getSubFacetDefinition

      public DfFacetDefinition getSubFacetDefinition()

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • copy

      public DfFacetDefinition copy()
      Deep copy of this object.