Package com.yahoo.search.query.profile

Class QueryProfile

  • All Implemented Interfaces:
    com.yahoo.component.Component, com.yahoo.component.Deconstructable, com.yahoo.component.provider.Freezable, java.lang.Cloneable, java.lang.Comparable<com.yahoo.component.Component>
    Direct Known Subclasses:
    OverridableQueryProfile
    public class QueryProfile
extends com.yahoo.component.provider.FreezableSimpleComponent
implements java.lang.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 Summary

      • Fields inherited from class com.yahoo.component.AbstractComponent

        isDeconstructable

    • Constructor Summary

      Constructors 
      Constructor Description
      QueryProfile​(com.yahoo.component.ComponentId id)
      Creates a new query profile from an id.
      QueryProfile​(com.yahoo.component.ComponentId id, java.lang.String sourceName)  
      QueryProfile​(java.lang.String idString)
      Convenience shorthand for new QueryProfile(new ComponentId(idString))

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected void accept​(com.yahoo.search.query.profile.QueryProfileVisitor visitor, DimensionBinding dimensionBinding, QueryProfile owner)  
      void addInherited​(QueryProfile profile)
      Adds a profile to the end of the inherited list of this.
      void addInherited​(QueryProfile profile, DimensionValues dimensionValues)
      Adds a profile to the end of the inherited list of this for the given variant.
      void addInherited​(QueryProfile profile, java.lang.String[] dimensionValues)  
      protected java.lang.Object checkAndConvertAssignment​(java.lang.String localName, java.lang.Object value, QueryProfileRegistry registry)
      Converts to the type of the receiving field, if possible and necessary.
      QueryProfile clone()
      Returns a clone of this.
      CompiledQueryProfile compile​(CompiledQueryProfileRegistry registry)
      Returns a compiled version of this which produces faster lookup times
      protected java.lang.Object convertToSubstitutionString​(java.lang.Object value)
      Returns this value, or its corresponding substitution string if it contains substitutions
      protected QueryProfile createSubProfile​(java.lang.String name, DimensionBinding dimensionBinding)
      Looks up all inherited profiles and adds any that matches this name.
      java.util.Map<java.lang.String,​java.lang.Object> declaredContent()
      Returns the content fields declared in this (i.e not including those inherited) as a read-only map.
      void freeze()
      Switches this from write-only to read-only mode.
      java.lang.Object get​(com.yahoo.processing.request.CompoundName name, java.util.Map<java.lang.String,​java.lang.String> context, com.yahoo.processing.request.Properties substitution)  
      java.lang.Object get​(java.lang.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.
      java.lang.Object get​(java.lang.String name, DimensionValues dimensionValues, com.yahoo.processing.request.Properties substitution)
      Returns a value from this using the given dimensions for resolution
      java.lang.Object get​(java.lang.String name, java.lang.String[] dimensionValues)
      Returns a value from this using the given dimensions for resolution
      java.lang.Object get​(java.lang.String name, java.lang.String[] dimensionValues, com.yahoo.processing.request.Properties substitution)  
      java.lang.Object get​(java.lang.String name, java.util.Map<java.lang.String,​java.lang.String> context)
      Returns a value from this using the given property context for resolution and using this for substitution
      java.lang.Object get​(java.lang.String name, java.util.Map<java.lang.String,​java.lang.String> context, com.yahoo.processing.request.Properties substitution)  
      protected java.util.Map<java.lang.String,​java.lang.Object> getContent()
      Returns all the content from this as an unmodifiable map
      protected java.lang.Object getContent​(java.lang.String key)
      Returns a value from the content of this, or null if not present
      java.util.List<java.lang.String> getDimensions()
      Returns the variant dimensions to be used in this - an unmodifiable list of dimension names
      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
      java.lang.String getSource()  
      QueryProfileType getType()
      Returns the type of this or null if it has no type
      java.lang.Object getValue()
      Returns the value set at this node, to allow non-leafs to have values.
      QueryProfileVariants getVariants()
      Returns the virtual variants of this, or null if none
      java.util.List<QueryProfile> inherited()
      Returns the list of profiles inherited by this.
      java.lang.Boolean isDeclaredOverridable​(java.lang.String name, java.util.Map<java.lang.String,​java.lang.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).
      boolean isExplicit()  
      protected java.lang.Boolean isLocalInstanceOverridable​(java.lang.String localName)  
      java.util.Map<java.lang.String,​java.lang.Object> listValues​(com.yahoo.processing.request.CompoundName prefix)
      Return all objects that start with the given prefix path using no context.
      java.util.Map<java.lang.String,​java.lang.Object> listValues​(com.yahoo.processing.request.CompoundName prefix, java.util.Map<java.lang.String,​java.lang.String> context)
      Return all objects that start with the given prefix path.
      java.util.Map<java.lang.String,​java.lang.Object> listValues​(com.yahoo.processing.request.CompoundName prefix, java.util.Map<java.lang.String,​java.lang.String> context, com.yahoo.processing.request.Properties substitution)
      Adds all objects that start with the given path prefix to the given value map.
      java.util.Map<java.lang.String,​java.lang.Object> listValues​(java.lang.String prefix)
      Return all objects that start with the given prefix path using no context.
      java.util.Map<java.lang.String,​java.lang.Object> listValues​(java.lang.String prefix, java.util.Map<java.lang.String,​java.lang.String> context)
      Return all objects that start with the given prefix path.
      protected java.lang.Object localLookup​(java.lang.String name, DimensionBinding dimensionBinding)
      Do a variant-aware content lookup in this
      protected java.lang.Object lookup​(com.yahoo.processing.request.CompoundName name, boolean allowQueryProfileResult, DimensionBinding dimensionBinding)  
      java.lang.Object lookup​(java.lang.String name, java.util.Map<java.lang.String,​java.lang.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.
      protected void set​(com.yahoo.processing.request.CompoundName name, java.lang.Object value, DimensionBinding binding, QueryProfileRegistry registry)
      Override this to intercept all writes to this profile (or any nested profiles)
      void set​(com.yahoo.processing.request.CompoundName name, java.lang.Object value, java.util.Map<java.lang.String,​java.lang.String> context, QueryProfileRegistry registry)
      Sets a value in this or any nested profile.
      void set​(java.lang.String name, java.lang.Object value, DimensionValues dimensionValues, QueryProfileRegistry registry)
      Sets a value in this or any nested profile.
      void set​(java.lang.String name, java.lang.Object value, QueryProfileRegistry registry)
      Sets a value in this or any nested profile using null as context
      void set​(java.lang.String name, java.lang.Object value, java.lang.String[] dimensionValues, QueryProfileRegistry registry)  
      void set​(java.lang.String name, java.lang.Object value, java.util.Map<java.lang.String,​java.lang.String> context, QueryProfileRegistry registry)  
      void setDimensions​(java.lang.String[] dimensions)
      Sets the dimensions over which this may vary.
      protected QueryProfile setLocalNode​(java.lang.String localName, java.lang.Object value, QueryProfileType parentType, DimensionBinding dimensionBinding, QueryProfileRegistry registry)
      Sets the value of a node in this profile - the local name given must not be nested (contain dots)
      void setOverridable​(java.lang.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)
      void setOverridable​(java.lang.String fieldName, boolean overridable, java.util.Map<java.lang.String,​java.lang.String> context)
      Sets the overridability of a field in this profile, this overrides the corresponding setting in the type (if any)
      void setType​(QueryProfileType type)
      Sets the type of this, or set to null to not use any type checking in this profile
      void setValue​(java.lang.Object value)  
      java.lang.String toString()  
      static void validateName​(java.lang.String name)
      Throws IllegalArgumentException if the given string is not a valid query profile name
      protected void visitInherited​(boolean allowContent, com.yahoo.search.query.profile.QueryProfileVisitor visitor, DimensionBinding dimensionBinding, QueryProfile owner)  
      protected void visitVariants​(boolean allowContent, com.yahoo.search.query.profile.QueryProfileVisitor visitor, DimensionBinding dimensionBinding)  

      • Methods inherited from class com.yahoo.component.provider.FreezableSimpleComponent

        ensureNotFrozen, isFrozen

      • Methods inherited from class com.yahoo.component.AbstractComponent

        compareTo, deconstruct, getClassName, getId, getIdString, hasInitializedId, initId, isDeconstructable, setIsDeconstructable

      • Methods inherited from class java.lang.Object

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

    • 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​(java.lang.String idString)
        Convenience shorthand for new QueryProfile(new ComponentId(idString))

      • QueryProfile

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

    • Method Detail

      • getSource

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

      • isDeclaredOverridable

        public java.lang.Boolean isDeclaredOverridable​(java.lang.String name,
                                               java.util.Map<java.lang.String,​java.lang.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:
        java.lang.IllegalStateException - if this is frozen

      • setDimensions

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

      • getValue

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

      • setValue

        public void setValue​(java.lang.Object value)

      • getDimensions

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

      • setOverridable

        public final void setOverridable​(java.lang.String fieldName,
                                 boolean overridable,
                                 java.util.Map<java.lang.String,​java.lang.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​(java.lang.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 java.util.Map<java.lang.String,​java.lang.Object> listValues​(java.lang.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 java.util.Map<java.lang.String,​java.lang.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 java.util.Map<java.lang.String,​java.lang.Object> listValues​(java.lang.String prefix,
                                                                               java.util.Map<java.lang.String,​java.lang.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 java.util.Map<java.lang.String,​java.lang.Object> listValues​(com.yahoo.processing.request.CompoundName prefix,
                                                                               java.util.Map<java.lang.String,​java.lang.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 java.util.Map<java.lang.String,​java.lang.Object> listValues​(com.yahoo.processing.request.CompoundName prefix,
                                                                         java.util.Map<java.lang.String,​java.lang.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 java.lang.Object get​(java.lang.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 java.lang.Object get​(java.lang.String name,
                                  java.util.Map<java.lang.String,​java.lang.String> context)
        Returns a value from this using the given property context for resolution and using this for substitution

      • get

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

      • get

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

      • get

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

      • get

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

      • get

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

      • lookup

        public final java.lang.Object lookup​(java.lang.String name,
                                     java.util.Map<java.lang.String,​java.lang.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​(java.lang.String name,
                      java.lang.Object value,
                      QueryProfileRegistry registry)
        Sets a value in this or any nested profile using null as context

      • set

        public final void set​(com.yahoo.processing.request.CompoundName name,
                      java.lang.Object value,
                      java.util.Map<java.lang.String,​java.lang.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:
        java.lang.IllegalArgumentException - if the given name is illegal given the types of this or any nested query profile
        java.lang.IllegalStateException - if this query profile is frozen

      • set

        public final void set​(java.lang.String name,
                      java.lang.Object value,
                      java.util.Map<java.lang.String,​java.lang.String> context,
                      QueryProfileRegistry registry)

      • set

        public final void set​(java.lang.String name,
                      java.lang.Object value,
                      java.lang.String[] dimensionValues,
                      QueryProfileRegistry registry)

      • set

        public final void set​(java.lang.String name,
                      java.lang.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:
        java.lang.IllegalArgumentException - if the given name is illegal given the types of this or any nested query profile
        java.lang.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 java.lang.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​(java.lang.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,
                   java.lang.Object value,
                   DimensionBinding binding,
                   QueryProfileRegistry registry)
        Override this to intercept all writes to this profile (or any nested profiles)

      • convertToSubstitutionString

        protected java.lang.Object convertToSubstitutionString​(java.lang.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 java.lang.Boolean isLocalInstanceOverridable​(java.lang.String localName)

      • lookup

        protected java.lang.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 java.lang.Object getContent​(java.lang.String key)
        Returns a value from the content of this, or null if not present

      • getContent

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

      • checkAndConvertAssignment

        protected java.lang.Object checkAndConvertAssignment​(java.lang.String localName,
                                                     java.lang.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:
        java.lang.IllegalArgumentException - if the assignment is illegal

      • createSubProfile

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

      • localLookup

        protected java.lang.Object localLookup​(java.lang.String name,
                                       DimensionBinding dimensionBinding)
        Do a variant-aware content lookup in this

      • 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