org.eclipse.viatra.query.runtime.matchers.backend

## Class QueryHintOption<HintValue>

- java.lang.Object
- - org.eclipse.viatra.query.runtime.matchers.backend.QueryHintOption<HintValue>

-     public class QueryHintOption<HintValue>
      extends java.lang.Object

  Each instance of this class corresponds to a given hint option. It is recommended to expose options to clients (and query backends) as public static fields.
  Since:
    1.5

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `QueryHintOption(java.lang.Class<?> optionNamespace, java.lang.String optionLocalName, T defaultValue)` This is the recommended constructor for hint options defined as static fields within an enclosing class.
    `QueryHintOption(java.lang.String optionQualifiedName, HintValue defaultValue)` Instantiates an option object with the given name and default value.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `HintValue` | `getDefaultValue()` Returns the default value of this hint option, which is to be used by query backends in the case no overriding value is assigned.
    `java.lang.String` | `getQualifiedName()` Returns the qualified name, a unique string identifier of the option.
    `HintValue` | `getValueOrDefault(QueryEvaluationHint hints)` Returns the value of this hint option from the given hint collection, or the default value if not defined.
    `HintValue` | `getValueOrNull(QueryEvaluationHint hints)` Returns the value of this hint option from the given hint collection, or null if not defined.
    `HintValue` | `insertOverridingValue(java.util.Map<QueryHintOption<?>,java.lang.Object> hints, HintValue overridingValue)` Puts a value of this hint option into an option-to-value map.
    `void` | `insertValueIfNondefault(java.util.Map<QueryHintOption<?>,java.lang.Object> hints, HintValue overridingValue)` Puts a value of this hint option into an option-to-value map, if the given value differs from the default value of the option.
    `boolean` | `isOverriddenIn(QueryEvaluationHint hints)` Returns whether this hint option is defined in the given hint collection.
    `java.lang.String` | `toString()`

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

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

- - ### Constructor Detail

    - #### QueryHintOption

          public QueryHintOption(java.lang.String optionQualifiedName,
                                 HintValue defaultValue)

      Instantiates an option object with the given name and default value.

    - #### QueryHintOption

          public QueryHintOption(java.lang.Class<?> optionNamespace,
                                 java.lang.String optionLocalName,
                                 T defaultValue)

      This is the recommended constructor for hint options defined as static fields within an enclosing class. Combines the qualified name of the hint from the (qualified) name of the enclosing class and a local name (unique within that class).

  - ### Method Detail

    - #### getQualifiedName

          public java.lang.String getQualifiedName()

      Returns the qualified name, a unique string identifier of the option.

    - #### getDefaultValue

          public HintValue getDefaultValue()

      Returns the default value of this hint option, which is to be used by query backends in the case no overriding value is assigned.

    - #### getValueOrDefault

          public HintValue getValueOrDefault(QueryEvaluationHint hints)

      Returns the value of this hint option from the given hint collection, or the default value if not defined. Intended to be called by backends to find out the definitive value that should be considered.

    - #### getValueOrNull

          public HintValue getValueOrNull(QueryEvaluationHint hints)

      Returns the value of this hint option from the given hint collection, or null if not defined.

    - #### isOverriddenIn

          public boolean isOverriddenIn(QueryEvaluationHint hints)

      Returns whether this hint option is defined in the given hint collection.

    - #### insertOverridingValue

          public HintValue insertOverridingValue(java.util.Map<QueryHintOption<?>,java.lang.Object> hints,
                                                 HintValue overridingValue)

      Puts a value of this hint option into an option-to-value map.

      This method is offered in lieu of a builder API. Use this method on any number of hint options in order to populate an option-value map. Then instantiate the immutable `QueryEvaluationHint` using the map.

      Returns:
        the hint value that was previously present in the map under this hint option, carrying over the semantics of `Map.put(Object, Object)`.
      See Also:
        `insertValueIfNondefault(Map, Object)`

    - #### insertValueIfNondefault

          public void insertValueIfNondefault(java.util.Map<QueryHintOption<?>,java.lang.Object> hints,
                                              HintValue overridingValue)

      Puts a value of this hint option into an option-to-value map, if the given value differs from the default value of the option. If the default value is provided instead, then the map is not updated.

      This method is offered in lieu of a builder API. Use this method on any number of hint options in order to populate an option-value map. Then instantiate the immutable `QueryEvaluationHint` using the map.

      Since:
        2.0
      See Also:
        `insertOverridingValue(Map, Object)`

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`