Package com.yahoo.search.query.profile

Class QueryProfile

  • All Implemented Interfaces:
    com.yahoo.component.Component, com.yahoo.component.Deconstructable, com.yahoo.component.provider.Freezable, Cloneable, Comparable<com.yahoo.component.Component>
    Direct Known Subclasses:
    OverridableQueryProfile
    public class QueryProfile
extends com.yahoo.component.provider.FreezableSimpleComponent
implements Cloneable
    A query profile is a data container with an id and a class (type). More precisely, it contains
    • An id, on the form name:version, where the version is optional, and follows the same rules as for other search container components.
    • A class id referring to the class defining this profile (see Query Profile Classes below)
    • A (possibly empty) list of ids of inherited query profiles
    • A (possibly empty) list of declarative predicates over search request parameters which defines when this query profile is applicable (see Query Profile Selection below)
    • The data content, which consists of
      • named values
      • named references to other profiles
    This serves the purpose of an intermediate format between configuration and runtime structures - the runtime structure used is QueryProfileProperties.
    Author:
    bratseth

    • Field Detail

      • owner

        public final QueryProfileRegistry owner
        The query profile registry owning this, or null if none (which will only happen in tests)

    • Constructor Detail

      • QueryProfile

        public QueryProfile​(com.yahoo.component.ComponentId id)
        Creates a new query profile from an id. The query profile can be modified freely (but not accessed) until it is frozen. At that point it becomes readable but unmodifiable, which it stays until it goes out of reference.

      • QueryProfile

        public QueryProfile​(String idString)
        Convenience shorthand for new QueryProfile(new ComponentId(idString))

      • QueryProfile

        public QueryProfile​(com.yahoo.component.ComponentId id,
                    String sourceName)

    • Method Detail

      • getSource

        public String getSource()

      • getType

        public QueryProfileType getType()
        Returns the type of this or null if it has no type

      • setType

        public void setType​(QueryProfileType type)
        Sets the type of this, or set to null to not use any type checking in this profile

      • getVariants

        public QueryProfileVariants getVariants()
        Returns the virtual variants of this, or null if none

      • inherited

        public List<QueryProfile> inherited()
        Returns the list of profiles inherited by this. Note that order matters for inherited profiles - variables are resolved depth first in the order found in the inherited list. This always returns an unmodifiable list - use addInherited to add.

      • addInherited

        public void addInherited​(QueryProfile profile)
        Adds a profile to the end of the inherited list of this. Throws an exception if this is frozen.

      • addInherited

        public final void addInherited​(QueryProfile profile,
                               String[] dimensionValues)

      • addInherited

        public void addInherited​(QueryProfile profile,
                         DimensionValues dimensionValues)
        Adds a profile to the end of the inherited list of this for the given variant. Throws an exception if this is frozen.

      • declaredContent

        public Map<String,​Object> declaredContent()
        Returns the content fields declared in this (i.e not including those inherited) as a read-only map.
        Throws:
        IllegalStateException - if this is frozen

      • isDeclaredOverridable

        public Boolean isDeclaredOverridable​(String name,
                                     Map<String,​String> context)
        Returns if the given field is declared explicitly as overridable or not in this or any nested profiles (i.e not including overridable settings inherited and from types).
        Parameters:
        name - the (possibly dotted) field name to return
        context - the context in which the name is resolved, or null if none
        Returns:
        true/false if this is declared overridable/not overridable in this instance, null if it is not given any value is this profile instance
        Throws:
        IllegalStateException - if this is frozen

      • setDimensions

        public void setDimensions​(String[] dimensions)
        Sets the dimensions over which this may vary. Note: This will erase any currently defined variants

      • getValue

        public Object getValue()
        Returns the value set at this node, to allow non-leafs to have values. Returns null if none.

      • setValue

        public void setValue​(Object value)

      • getDimensions

        public List<String> getDimensions()
        Returns the variant dimensions to be used in this - an unmodifiable list of dimension names

      • setOverridable

        public final void setOverridable​(String fieldName,
                                 boolean overridable,
                                 Map<String,​String> context)
        Sets the overridability of a field in this profile, this overrides the corresponding setting in the type (if any)

      • setOverridable

        public final void setOverridable​(String fieldName,
                                 boolean overridable,
                                 DimensionValues dimensionValues)
        Sets the overridability of a field in this profile, this overrides the corresponding setting in the type (if any)

      • listValues

        public final Map<String,​Object> listValues​(String prefix)
        Return all objects that start with the given prefix path using no context. Use "" to list all.

        For example, if {a.d => "a.d-value" ,a.e => "a.e-value", b.d => "b.d-value", then calling listValues("a") will return {"d" => "a.d-value","e" => "a.e-value"}

      • listValues

        public final Map<String,​Object> listValues​(com.yahoo.processing.request.CompoundName prefix)
        Return all objects that start with the given prefix path using no context. Use "" to list all.

        For example, if {a.d => "a.d-value" ,a.e => "a.e-value", b.d => "b.d-value", then calling listValues("a") will return {"d" => "a.d-value","e" => "a.e-value"}

      • listValues

        public final Map<String,​Object> listValues​(String prefix,
                                                 Map<String,​String> context)
        Return all objects that start with the given prefix path. Use "" to list all.

        For example, if {a.d => "a.d-value" ,a.e => "a.e-value", b.d => "b.d-value", then calling listValues("a") will return {"d" => "a.d-value","e" => "a.e-value"}

      • listValues

        public final Map<String,​Object> listValues​(com.yahoo.processing.request.CompoundName prefix,
                                                 Map<String,​String> context)
        Return all objects that start with the given prefix path. Use "" to list all.

        For example, if {a.d => "a.d-value" ,a.e => "a.e-value", b.d => "b.d-value", then calling listValues("a") will return {"d" => "a.d-value","e" => "a.e-value"}

      • listValues

        public Map<String,​Object> listValues​(com.yahoo.processing.request.CompoundName prefix,
                                           Map<String,​String> context,
                                           com.yahoo.processing.request.Properties substitution)
        Adds all objects that start with the given path prefix to the given value map. Use "" to list all.

        For example, if {a.d => "a.d-value" ,a.e => "a.e-value", b.d => "b.d-value", then calling listValues("a") will return {"d" => "a.d-value","e" => "a.e-value"}

      • get

        public final Object get​(String name)
        Returns a value from this query profile by resolving the given name:
        • The name up to the first dot is the value looked up in the value of this profile
        • The rest of the name (if any) is used as the name to look up in the referenced query profile
        If this name does not resolve completely into a value in this or any inherited profile, null is returned.

      • get

        public final Object get​(String name,
                        Map<String,​String> context)
        Returns a value from this using the given property context for resolution and using this for substitution

      • get

        public final Object get​(String name,
                        String[] dimensionValues)
        Returns a value from this using the given dimensions for resolution

      • get

        public final Object get​(String name,
                        String[] dimensionValues,
                        com.yahoo.processing.request.Properties substitution)

      • get

        public final Object get​(String name,
                        DimensionValues dimensionValues,
                        com.yahoo.processing.request.Properties substitution)
        Returns a value from this using the given dimensions for resolution

      • get

        public final Object get​(String name,
                        Map<String,​String> context,
                        com.yahoo.processing.request.Properties substitution)

      • get

        public final Object get​(com.yahoo.processing.request.CompoundName name,
                        Map<String,​String> context,
                        com.yahoo.processing.request.Properties substitution)

      • lookup

        public final Object lookup​(String name,
                           Map<String,​String> context)
        Returns the node at the position prescribed by the given name (without doing substitutions) - a primitive value, a substitutable string, a query profile, or null if not found.

      • set

        public final void set​(com.yahoo.processing.request.CompoundName name,
                      Object value,
                      Map<String,​String> context,
                      QueryProfileRegistry registry)
        Sets a value in this or any nested profile. Any missing structure needed to set this will be created. If this value is already set, this will overwrite the previous value.
        Parameters:
        name - the name of the field, possibly a dotted name which will cause setting of a variable in a subprofile
        value - the value to assign to the name, a primitive wrapper, string or a query profile
        context - the context used to resolve where this value should be set, or null if none
        Throws:
        IllegalArgumentException - if the given name is illegal given the types of this or any nested query profile
        IllegalStateException - if this query profile is frozen

      • set

        public final void set​(String name,
                      Object value,
                      DimensionValues dimensionValues,
                      QueryProfileRegistry registry)
        Sets a value in this or any nested profile. Any missing structure needed to set this will be created. If this value is already set, this will overwrite the previous value.
        Parameters:
        name - the name of the field, possibly a dotted name which will cause setting of a variable in a subprofile
        value - the value to assign to the name, a primitive wrapper, string or a query profile
        dimensionValues - the dimension values - will be matched by order to the dimensions set in this - if this is shorter or longer than the number of dimensions it will be adjusted as needed
        registry - the registry used to resolve query profile references. If null is passed query profile references will cause an exception
        Throws:
        IllegalArgumentException - if the given name is illegal given the types of this or any nested query profile
        IllegalStateException - if this query profile is frozen

      • isExplicit

        public boolean isExplicit()

      • freeze

        public void freeze()
        Switches this from write-only to read-only mode. This profile can never be modified again after this method returns. Calling this on an already frozen profile has no effect. Calling this will also freeze any profiles inherited and referenced by this.
        Specified by:
        freeze in interface com.yahoo.component.provider.Freezable
        Overrides:
        freeze in class com.yahoo.component.provider.FreezableSimpleComponent

      • toString

        public String toString()
        Overrides:
        toString in class com.yahoo.component.AbstractComponent

      • clone

        public QueryProfile clone()
        Returns a clone of this. The clone will not be frozen and will contain copied inherited and content collections pointing to the same values as this.
        Overrides:
        clone in class com.yahoo.component.provider.FreezableSimpleComponent

      • validateName

        public static void validateName​(String name)
        Throws IllegalArgumentException if the given string is not a valid query profile name

      • set

        protected void set​(com.yahoo.processing.request.CompoundName name,
                   Object value,
                   DimensionBinding binding,
                   QueryProfileRegistry registry)
        Override this to intercept all writes to this profile (or any nested profiles)

      • convertToSubstitutionString

        protected Object convertToSubstitutionString​(Object value)
        Returns this value, or its corresponding substitution string if it contains substitutions

      • getFieldDescription

        protected FieldDescription getFieldDescription​(com.yahoo.processing.request.CompoundName name,
                                               DimensionBinding binding)
        Returns the field description of this field, or null if it is not typed

      • isLocalInstanceOverridable

        protected Boolean isLocalInstanceOverridable​(String localName)

      • lookup

        protected Object lookup​(com.yahoo.processing.request.CompoundName name,
                        boolean allowQueryProfileResult,
                        DimensionBinding dimensionBinding)

      • accept

        protected final void accept​(com.yahoo.search.query.profile.QueryProfileVisitor visitor,
                            DimensionBinding dimensionBinding,
                            QueryProfile owner)

      • visitVariants

        protected void visitVariants​(boolean allowContent,
                             com.yahoo.search.query.profile.QueryProfileVisitor visitor,
                             DimensionBinding dimensionBinding)

      • visitInherited

        protected void visitInherited​(boolean allowContent,
                              com.yahoo.search.query.profile.QueryProfileVisitor visitor,
                              DimensionBinding dimensionBinding,
                              QueryProfile owner)

      • getContent

        protected Object getContent​(String key)
        Returns a value from the content of this, or null if not present

      • getContent

        protected Map<String,​Object> getContent()
        Returns all the content from this as an unmodifiable map

      • checkAndConvertAssignment

        protected Object checkAndConvertAssignment​(String localName,
                                           Object value,
                                           QueryProfileRegistry registry)
        Converts to the type of the receiving field, if possible and necessary.
        Returns:
        the value to be assigned: the original or a converted value
        Throws:
        IllegalArgumentException - if the assignment is illegal

      • createSubProfile

        protected QueryProfile createSubProfile​(String name,
                                        DimensionBinding dimensionBinding)
        Looks up all inherited profiles and adds any that matches this name. This default implementation returns an empty profile.

      • compile

        public CompiledQueryProfile compile​(CompiledQueryProfileRegistry registry)
        Returns a compiled version of this which produces faster lookup times
        Parameters:
        registry - the registry this will be added to by the caller, or null if none