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:
  - `setGroupBy(String)`
  - `IDfFacet`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `DfFacetDefinition.ORDER`
  Define the order of the facet value in the returned facets.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DfFacetDefinition(String name)`
  Create a new definition.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addAttribute(String attr)`
  Add an attribute to use for facet computation.
  `DfFacetDefinition`
  `copy()`
  Deep copy of this object.
  `boolean`
  `equals(Object o)`
  `List<String>`
  `getAttributes()`
  Get the list of attributes used for facet computation.
  `String`
  `getGroupBy()`
  Get the grouping startegy used for this facet.
  `Integer`
  `getMax()`
  Get the maximum number of facet.
  `String`
  `getName()`
  Get the name for the facet
  `DfFacetDefinition.ORDER`
  `getOrderBy()`
  Get the sorting order used for facet values returned.
  `Map<String,String>`
  `getProperties()`
  `String`
  `getProperty(String name)`
  `DfFacetDefinition`
  `getSubFacetDefinition()`
  `int`
  `hashCode()`
  `boolean`
  `hasMax()`
  Indicate if the definition specified a maximum number of facets
  `void`
  `setAttributes(Collection<String> attrs)`
  Set the list of attributes to use for facet computation.
  `void`
  `setGroupBy(String groupBy)`
  Set the grouping used to compute facets.
  `void`
  `setMax(Integer max)`
  Set the maximum number of facets value.
  `void`
  `setName(String name)`
  Set the name for the facet
  `void`
  `setOrderBy(DfFacetDefinition.ORDER orderBy)`
  Set the sorting order used for facet values returned.
  `void`
  `setProperty(String name, String value)`
  Set a custom property to be used for certain grouping strategy.
  `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'.
  `String`
  `toString()`

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## 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(String)`

  - ### 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:
      - `setProperty(String, String)`

  - ### 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.