Package com.activeviam.activepivot.core.intf.api.location

Interface ILocation

All Known Subinterfaces:
ILocationBuilder, IPointLocation, IPointLocationReader, IScopeLocation
All Known Implementing Classes:
AbstractSubLocation, APointLocationListReader, ASubPointLocation, ImmutableSubPointLocation, Location, LocationBuilder, ModifiedLocation, MutableSubLocation, MutableSubPointLocation, PartialExpandLocation, PartialExpandLocationWithParent, PointLocation, PointLocationListReader, PointLocationListReader.ImmutablePointLocationListReader, ScopeLocation, StandardScopeLocation, SubLocation
public interface ILocation
An ILocation represents the path to one or several cells in a cube.

It specifies for each hierarchy (but the measure hierarchy) a path to axis member(s). Because the measure hierarchy is omitted, the index of a hierarchy in a location is equal to the ordinal of the hierarchy minus 1 i.e. the code to iterate over a path along a hierarchy in a location is as follow: 

     final IHierarchy myHierarchy = ...;
    final ILocation myLocation = ...;
    final int myHierarchyOrdinal = myHierarchy.getOrdinal();
    final int myHierarchyIndexInLocation = myHierarchyOrdinal - 1;
    for(int levelOrdinal = 0; levelOrdinal invalid input: '<' myLocation.getLevelDepth(myHierarchyIndexInLocation); levelOrdinal ++) {
       //Read the discriminator for the level of ordinal levelOrdinal of hierarchy myHierarchy
       final Object pathDiscriminator = myLocation.getCoordinate(myHierarchyIndexInLocation, levelOrdinal);
       ...
    }

The coordinates in the location are Objects and will be matched with axis members discriminator.

There are two main types of locations:

  • Simple, fully-specified locations. They point at a single cell in the cube. E.g. 
       [
     [AllMember, DeskA], //<-- points at the axis member of path 'AllMember\DeskA' in the hierarchy of ordinal 1
     [AllMember, EUR], //<-- points at the axis member of path 'AllMember\EUR' in the hierarchy of ordinal 2
     [Today] //<-- points at the axis member of path 'Today' in the hierarchy of ordinal 3
   ]
  • Range locations. They point at a one or more cells in the cube. They allow wild-cards in order to describe patterns. Wild-cards can be null coordinates or collections of discriminators. As soon as a location contains one of those it is a range location. E.g. 
       [
     [AllMember, null], //<-- points at all axis members children of 'AllMember' in the hierarchy of ordinal 1
     [AllMember, {EUR, USD}], //<-- points at the axis members of path 'AllMember\EUR' and 'AllMember\USD' in the hierarchy of ordinal 2
     [Today] //<-- points at the axis member of path 'Today' in the hierarchy of ordinal 3
   ]
Note that a path along a hierarchy in a location can be totally empty or null (e.g. [ [AllMember, null], null, [Today] ] or [ [AllMember, null], [], [Today] ]) for the specific case of expand (IExpandLocationsQuery).
Author:
ActiveViam

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    DEFAULT_HIERARCHY_SEPARATOR
    The default hierarchy separator sequence.
    static final String
    DEFAULT_LEVEL_SEPARATOR
    The default level separator sequence.
    static final String
    DEFAULT_WILDCARD
    The default wildcard sequence.
    static final String
    HIERARCHY_SEPARATOR
    Separator for the coordinates to segregate hierarchies as in USD|Books.
    static final String
    LEVEL_SEPARATOR
    Separator for the coordinates to segregate a levels as in Books\ScienceFiction.
    static final String
    WILDCARD
    The sequence representing a wildcard.
    static final int
    WILDCARD_HASHCODE
    Hashcode attributed to a wildcard ("null" coordinate).

  • Method Summary

    Modifier and Type
    Method
    Description
    Object[][]
    arrayCopy()
    Returns plain array representation of the location.
    ILocationPattern
    createPattern(boolean[][] pattern)
    Creates a location pattern from this location.
    ILocationPattern
    createRangeCoordPattern()
    Creates a location pattern indicating which coordinates are range locations.
    boolean
    equals(Object other)
    Two locations are equal if they express exactly the same coordinates and that those coordinates are themselves equal.
    Object
    getCoordinate(int hierarchyIndex, int levelIndex)
    Returns the coordinate at the given hierarchy and given level depth.
    int
    getHierarchyCount()
    Returns the number of hierarchies expressed in that location.
    int
    getLevelDepth(int hierarchyIndex)
    Returns the number of expressed levels within a hierarchy.
    int
    hashCode()
    Special implementation of Object.hashCode() for locations.
    boolean
    isRange()
    A location is called "range" when it contains wildcards or collections of members on specific levels.

  • Field Details

    • WILDCARD_HASHCODE

      static final int WILDCARD_HASHCODE
      Hashcode attributed to a wildcard ("null" coordinate).
      See Also:

    • DEFAULT_HIERARCHY_SEPARATOR

      static final String DEFAULT_HIERARCHY_SEPARATOR
      The default hierarchy separator sequence.
      See Also:

    • HIERARCHY_SEPARATOR

      static final String HIERARCHY_SEPARATOR
      Separator for the coordinates to segregate hierarchies as in USD|Books.

    • DEFAULT_LEVEL_SEPARATOR

      static final String DEFAULT_LEVEL_SEPARATOR
      The default level separator sequence.
      See Also:

    • LEVEL_SEPARATOR

      static final String LEVEL_SEPARATOR
      Separator for the coordinates to segregate a levels as in Books\ScienceFiction.

    • DEFAULT_WILDCARD

      static final String DEFAULT_WILDCARD
      The default wildcard sequence.
      See Also:

    • WILDCARD

      static final String WILDCARD
      The sequence representing a wildcard. Used for range locations.

  • Method Details

    • getHierarchyCount

      int getHierarchyCount()
      Returns the number of hierarchies expressed in that location.

    • getLevelDepth

      int getLevelDepth(int hierarchyIndex)
      Returns the number of expressed levels within a hierarchy.

      If the hierarchy is not expressed at all (null partial coordinate) this method returns 0. The depth returned is therefore 1-based.

    • getCoordinate

      Object getCoordinate(int hierarchyIndex, int levelIndex)
      Returns the coordinate at the given hierarchy and given level depth.

      The coordinate can be a range coordinate: a null value means either 'ANY' or an explicit collection of values.

    • arrayCopy

      Object[][] arrayCopy()
      Returns plain array representation of the location.

    • isRange

      boolean isRange()
      A location is called "range" when it contains wildcards or collections of members on specific levels.

      • A wildcard is represented by a null value inside the arrayLocation.
      • Multiple members are represented by a Collection of members.
      Returns:
      true if the location is range, false otherwise.

    • createPattern

      ILocationPattern createPattern(boolean[][] pattern)
      Creates a location pattern from this location.

      A location pattern is a component that will act as a generator for light-weight (but fully functional) locations. The input boolean double array specifies the elements that one wants to parameters for subsequent location generation.

      Example:
      Suppose the location { {o1, null}, null, {null} }
      The pattern { {false, true}, {false}, {false} } will let you generate locations such as { {o1, o2}, null, {null} } for any object o2 (null included). Note that the pattern { {false, true}, null, null } will have the same effect.
      The pattern { {false, true}, {true}, {true} } will let you generate locations such as { {o1, o2}, {o3}, {o4} } for any combination of objects {o2, o3, o4) (null included).

    • createRangeCoordPattern

      ILocationPattern createRangeCoordPattern()
      Creates a location pattern indicating which coordinates are range locations.

      For example: creating the range pattern on location { {o1, null}, null, {null} } is equivalent to creating the pattern { {false, true}, null, {true} } on that same location. The same pattern could also be obtained for reference location {{o1, o2}, null, {null}} if o2 implements Collection.

    • hashCode

      int hashCode()
      Special implementation of Object.hashCode() for locations.

      Location implementations obey a particular hashCode contract:

      • All location implementations of the location interface must be coherent, if two distinct location implementations represent the same logical location, their hashCode must be the same.
      • Hash code computation must be incremental with respect to the location coordinates. The hash code of the location is a linear combination of the hash codes of each expressed coordinate. When two locations differ by only one coordinate, the hash code of one location can be deduced from the other location's hashcode and just that coordinate.
      • A 'null' coordinate, a.k.a. 'wild card' has no contribution to the hash code of the location.
      To implement this contract and maintain a good hashCode behavior the contribution of the coordinate at hierarchy h and level l is:
      • partialHashCode(h, l) = LocationUtil.hashMix(h, l) * coordinate.hashCode()
      Overrides:
      hashCode in class Object

    • equals

      boolean equals(Object other)
      Two locations are equal if they express exactly the same coordinates and that those coordinates are themselves equal. Distinct location implementations can be equal if they represent the same logical location.
      Overrides:
      equals in class Object
      Returns:
      equality boolean