com.ibm.commerce.location.facade.server.commands

Class ResolveClientLocationCmdImpl

  • java.lang.Object
    • com.ibm.commerce.foundation.celadon.common.oagis.CeladonPipelineCmdImpl
      • com.ibm.commerce.location.facade.server.commands.ResolveClientLocationCmdImpl
  • All Implemented Interfaces:
    com.ibm.commerce.foundation.celadon.common.oagis.CeladonPipelineCmd, ResolveClientLocationCmd, com.ibm.websphere.command.Command, java.io.Serializable

    public class ResolveClientLocationCmdImpl
extends com.ibm.commerce.foundation.celadon.common.oagis.CeladonPipelineCmdImpl
implements ResolveClientLocationCmd
    Base class implementation for commands which resolve incoming requests to create or update client location nouns to a set of known points of interest -- the resolution may result in a set of output requests to create, update, or delete the incoming client location noun as well as other, preexisting client location nouns in the data service.

    Requests to create, update, or delete client location nouns are input to the command via the pipeline methods setNounsToBeCreated(), setNounsToBeUpdated(), or setNounsToBeDeleted(). The execute() method of the command makes logical decisions about the effect a given request to create, update, or delete a client location noun will have on the current set of client location nouns managed by the location service. The decisions are based upon a process of point of interest matching in which existing points of interest are matched to incoming client location noun to determine logical or physical relation. For example, it may be determined that a single incoming client location noun reports a physical position which overlaps with multiple points of interest. A decision may be made to expand the report by generating multiple output client location nouns, reflecting the simultaneous presence of the client at multiple points of interest. The resulting decisions are posted to the output noun lists which may be retrieved after execution via the pipeline methods getNounsToBeCreated(), getNounsToBeUpdated(), or getNounsToBeDeleted().

    The location service supports the possibility of recognizing that a given client may be located at multiple points of interest known by the location service. For example a GPS reading for a given client at a shopping mall may fall within the proximity of multiple shops at the shopping mall. In cases such as these, the single report that the client is at the physical location of the GPS reading may result in multiple client locations being reported to the location service, each corresponding to a single point of interest which represents a single shop at the shopping mall. Note that the command may be customized with specific settings which induce different behaviors regarding the processing of requested creations, updates, and deletes, and in particular the multiple reporting option may be turned on and off as desired.

    Requests are processed one by one from the input lists, as if each was received in order. In particular the appearance of two requests for a given client ID are treated as separate requests which have arrived sequentially.

    • Client location nouns found in the create and update request lists are merged into a list of incoming nouns and are essentially all treated in the same way. Logically this means there is no difference in a client initially appearing to the service (create) and the client moving from another location (update).
    • Client location nouns found in the delete request list pass through this pipeline command unchanged. A caller which wishes to delete a client location noun may simply place the noun in the delete list and it will be passed through to the data service and deleted without any pre-processing by this command.

    Gateway Test:

    The first step in processing is a gateway test which determines which incoming nouns are actually processed by this pipeline command and which are simply passed through. This gateway test is performed by the processIncomingNoun() method. If an incoming noun is to be further processed by this pipeline command the method returns true. If an incoming noun is not to be processed, and passed through the pipeline without alteration, the method returns false.

    The default implementation of the processIncomingNoun() method works as follows: The getPointOfInterestMatchingForAllSourceTypes() method is first checked to see if ALL incoming nouns are processed by the pipeline command. If so, the gateway test succeeds and the noun is processed without further inspection. If not, only nouns with selective source types (e.g., "GPS") are processed. The list of selective source types is returned by the getPointOfInterestMatchingSelectiveSourceTypes() method. The default processing provided by this base class supports only the "GPS" source type. Nouns which do not have a source type of "GPS" are simply passed through to the data service (they are not discarded!). Each of the key methods in the gateway test may be customized by overriding subclasses.

    Computing Working Sets:

    Once the gateway test has been passed by an incoming noun, two working sets of nouns are computed: a working set of existing client location nouns which match the incoming client location noun, and a working set of point of interest nouns which match the the incoming client location nouns. The logic for "matching" the incoming client location noun is determined as follows, and can be customized by subclasses which override key methods.

    First, a working set of existing client location nouns which corresponding to the incoming client location noun is obtained via the computeWorkingSetOfMatchingClientLocations() method. By default, this method performs a fetch from the data service to retrieve all preexisting client location nouns which match the client ID and store ID of the incoming client location noun. This may be overridden by subclasses, for example, by a subclass which wishes to implement a cache of client location nouns.

    Second, a working set of existing point of interest nouns which corresponding to the incoming client location noun is obtained via the computeWorkingSetOfMatchingPointsOfInterest() method. The base class implementation provides a matching process based upon geometric point of interest matching. This implementation maintains a cache of known point of interest nouns for each known store ID and compares the physical latitude, longitude, and accuracy values of the incoming client location noun with the the latitude, longitude, and radius of each existing point of interest which matches the client's store ID. This implementation may be overridden by subclasses, for example, by a subclass which wishes to implement a matching process that works at a smaller scale (e.g. inside a store) and does not use the metropolitan-scale matching which is more appropriate to "GPS" readings.

    The geometric matching of the default implementation proceeds as follows: For each candidate point of interest noun, the matching rule provided by getPointOfInterestMatchingRule() determines whether the point of interest noun will be added to the working set. This value may be overriden or set via the setPointOfInterestMatchingRule() method. The rule has one of three values, as follows:

    • POINT_OF_INTEREST_MATCH_NEAREST_ONLY: Indicating client location nouns match against only the nearest point of interest whose geometric area (as determined by its latitude, longitude and radius) intersect the geometric area of the client location (as determined by its latitude, longitude and accuracy) -- use of this matching rule means that the location of a client will be reported against only one point of interest at a time.

    • POINT_OF_INTEREST_MATCH_ALL_WITHIN_GEOMETRIC_AREA: (the default) Indicating client location nouns match against any point of interest whose geometric area (as determined by its latitude, longitude and radius) intersect the geometric area of the client location (as determined by its latitude, longitude and accuracy) -- use of this matching rule means that the location of a client may be reported against multiple points of interest simultaneously.

    • POINT_OF_INTEREST_MATCH_BY_HIGHEST_PRECEDENCE_WITHIN_GEOMETRIC_AREA: Indicating client location nouns match against the single point of interest whose geometric area (as determined by its latitude, longitude and radius) intersects the geometric area of the client location (as determined by its latitude, longitude and accuracy) and which has the highest precedence among all other matching points of interest -- use of this matching rule means that the location of a client will be reported against only one point of interest at a time.

    Working Set Resolution:

    • Nouns in the client location working set which correspond to a noun in the point of interest working set (i.e. the point of interest ID in the client location matches the unique ID of a point of interest) reflect a pre-existing association of the client location with a point of interest which does not change. These client location nouns are updated with information from the incoming client location noun and are placed in the outgoing update request list.

    • Nouns in the client location working set which do not correspond to noun in the point of interest working set reflect prior associations between the client and a point of interest that has now been broken (e.g. due to movement of the client away from the point of interest). These client location nouns are placed in the outgoing delete request list.

    • Points of interest nouns which remain in the point of interest working set indicate points of interest that are new to the client, and for each, a new client location noun is created corresponding to that point of interest. The new noun is cloned from the incoming noun, except for the client location ID, and is additionally updated from the point of interest. The newly constructed and updated noun is placed in the outgoing create request list.

    Updating Resolved Nouns:

    The resolution of the client location nouns is followed by a final step which updates the nouns before they are placed into the outgoing create, update, or delete lists.

    • Preexisting client location nouns which are placed into the update list by the resolution process are updated with the "fresher" information from the incoming client location noun. This update is performed via the updateExistingClientLocationNounFromIncomingClientLocationNoun() method. The default implementation of this method copies the latitude, longitude, altitude, accuracy, altitude accuracy, heading and speed fields from the incoming client location noun to the existing client location noun. The method may be customized by overriding subclasses.

    • Newly constructed client location nouns which are placed into the create list by the resolution process are initialized as a clone of the incoming noun (except for the unique client location ID) as note above, and are further updated from the point of interest noun via the updateIncomingClientLocationNounFromExistingPointOfInterestNoun() method. The default implementation of this method copies the unique ID, POI type, region ID, and zone ID from the point of interest noun to the new client location noun. The method may be customized by overriding subclasses.

    • Preexisting client location nouns which are placed into the delete list by the resolution process are not further updated or changed.

    See Also:
    Serialized Form

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method and Description
      boolean clientLocationsMatch(ClientLocationType incoming_client_location, ClientLocationType candidate_client_location)
      Determines if two individual ClientLocation nouns match each other for potential inclusion in the working set for the point of interest matching process.
      void execute()
      Searches the data service for ClientLocation objects that match the given ClientLocation object on these fields: ClientID, StoreID, RegionID, ZoneID
      boolean getPointOfInterestMatchingForAllSourceTypes()
      Retrieves the business logic directive which determines if point of interest matching logic is used for all incoming client location nouns, regardless of their source type setting -- if the value is false, then point of interest matching logic is used only for selective source types whose values appear in the array of strings returned by the getPointOfInterestMatchingSelectiveSourceTypes method.
      int getPointOfInterestMatchingRule()
      Retrieves the point of interest matching rule which determines which points of interest relate to client locations as they are reported to the service -- the rule will typicallys have one of the three values: ResolveClientLocationCmd.POINT_OF_INTEREST_MATCH_NEAREST_ONLY, ResolveClientLocationCmd.POINT_OF_INTEREST_MATCH_ALL_WITHIN_GEOMETRIC_AREA (the default) or ResolveClientLocationCmd.POINT_OF_INTEREST_MATCH_BY_HIGHEST_PRECEDENCE_WITHIN_GEOMETRIC_AREA.
      java.util.List getPointOfInterestMatchingSelectiveSourceTypes()
      Retrieves the list of selective source types for which point of interest matching logic is used on incoming client location nouns.
      void setPointOfInterestMatchingForAllSourceTypes(boolean point_of_interest_matching_for_all_source_types)
      Sets the business logic directive which determines if point of interest matching logic is used for all incoming client location nouns, regardless of their source type setting -- if the value is false, then point of interest matching logic is used only for selective source types whose values appear in the array of strings returned by the getPointOfInterestMatchingSelectiveSourceTypes method.
      void setPointOfInterestMatchingRule(int point_of_interest_matching_rule)
      Sets the point of interest matching rule which determines which points of interest relate to client locations as they are reported to the service -- the rule should have one of the three values: ResolveClientLocationCmd.POINT_OF_INTEREST_MATCH_NEAREST_ONLY, ResolveClientLocationCmd.POINT_OF_INTEREST_MATCH_ALL_WITHIN_GEOMETRIC_AREA (the default) or ResolveClientLocationCmd.POINT_OF_INTEREST_MATCH_BY_HIGHEST_PRECEDENCE_WITHIN_GEOMETRIC_AREA.
      void setPointOfInterestMatchingSelectiveSourceTypes(java.util.List point_of_interest_matching_selective_source_types)
      Sets the list of selective source types for which point of interest matching logic is used on incoming client location nouns.

      • Methods inherited from class com.ibm.commerce.foundation.celadon.common.oagis.CeladonPipelineCmdImpl

        getNounsToBeCreated, getNounsToBeDeleted, getNounsToBeUpdated, isReadyToCallExecute, reset, setNounsToBeCreated, setNounsToBeDeleted, setNounsToBeUpdated

      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

      • Methods inherited from interface com.ibm.commerce.foundation.celadon.common.oagis.CeladonPipelineCmd

        getNounsToBeCreated, getNounsToBeDeleted, getNounsToBeUpdated, setNounsToBeCreated, setNounsToBeDeleted, setNounsToBeUpdated

      • Methods inherited from interface com.ibm.websphere.command.Command

        isReadyToCallExecute, reset

    • Constructor Detail

      • ResolveClientLocationCmdImpl

        public ResolveClientLocationCmdImpl()
        Constructor

    • Method Detail

      • setPointOfInterestMatchingForAllSourceTypes

        public void setPointOfInterestMatchingForAllSourceTypes(boolean point_of_interest_matching_for_all_source_types)
        Sets the business logic directive which determines if point of interest matching logic is used for all incoming client location nouns, regardless of their source type setting -- if the value is false, then point of interest matching logic is used only for selective source types whose values appear in the array of strings returned by the getPointOfInterestMatchingSelectiveSourceTypes method.

        Parameters:
        point_of_interest_matching_for_all_source_types - Business logic directive which determines if point of interest matching logic is used for all incoming client location nouns, regardless of their source type setting.

      • getPointOfInterestMatchingForAllSourceTypes

        public boolean getPointOfInterestMatchingForAllSourceTypes()
        Retrieves the business logic directive which determines if point of interest matching logic is used for all incoming client location nouns, regardless of their source type setting -- if the value is false, then point of interest matching logic is used only for selective source types whose values appear in the array of strings returned by the getPointOfInterestMatchingSelectiveSourceTypes method.

        Returns:
        Business logic directive which determines if point of interest matching logic is used for all incoming client location nouns, regardless of their source type setting.

      • getPointOfInterestMatchingSelectiveSourceTypes

        public java.util.List getPointOfInterestMatchingSelectiveSourceTypes()
        Retrieves the list of selective source types for which point of interest matching logic is used on incoming client location nouns.

        Returns:
        List of selective source types for which point of interest matching logic is used on incoming client location nouns.

      • setPointOfInterestMatchingSelectiveSourceTypes

        public void setPointOfInterestMatchingSelectiveSourceTypes(java.util.List point_of_interest_matching_selective_source_types)
        Sets the list of selective source types for which point of interest matching logic is used on incoming client location nouns.

        Parameters:
        point_of_interest_matching_selective_source_types - List of selective source types for which point of interest matching logic is used on incoming client location nouns.

      • setPointOfInterestMatchingRule

        public void setPointOfInterestMatchingRule(int point_of_interest_matching_rule)
        Sets the point of interest matching rule which determines which points of interest relate to client locations as they are reported to the service -- the rule should have one of the three values: ResolveClientLocationCmd.POINT_OF_INTEREST_MATCH_NEAREST_ONLY, ResolveClientLocationCmd.POINT_OF_INTEREST_MATCH_ALL_WITHIN_GEOMETRIC_AREA (the default) or ResolveClientLocationCmd.POINT_OF_INTEREST_MATCH_BY_HIGHEST_PRECEDENCE_WITHIN_GEOMETRIC_AREA.

        Typically this value should be set within the constructor for a subclass of ResolveClientLocationCmdImpl to customize the behavioral logic of client location resolution.

        Parameters:
        point_of_interest_matching_rule - The point of interest matching rule which determines which points of interest relate to client locations as they are reported to the service.

      • getPointOfInterestMatchingRule

        public int getPointOfInterestMatchingRule()
        Retrieves the point of interest matching rule which determines which points of interest relate to client locations as they are reported to the service -- the rule will typicallys have one of the three values: ResolveClientLocationCmd.POINT_OF_INTEREST_MATCH_NEAREST_ONLY, ResolveClientLocationCmd.POINT_OF_INTEREST_MATCH_ALL_WITHIN_GEOMETRIC_AREA (the default) or ResolveClientLocationCmd.POINT_OF_INTEREST_MATCH_BY_HIGHEST_PRECEDENCE_WITHIN_GEOMETRIC_AREA.

        Returns:
        The point of interest matching rule which determines which points of interest relate to client locations as they are reported to the service.

      • execute

        public void execute()
             throws com.ibm.websphere.command.CommandException
        Searches the data service for ClientLocation objects that match the given ClientLocation object on these fields: ClientID, StoreID, RegionID, ZoneID
        Specified by:
        execute in interface com.ibm.websphere.command.Command
        Overrides:
        execute in class com.ibm.commerce.foundation.celadon.common.oagis.CeladonPipelineCmdImpl
        Throws:
        com.ibm.websphere.command.CommandException - A CommandException is thrown if an error occurs

      • clientLocationsMatch

        public boolean clientLocationsMatch(ClientLocationType incoming_client_location,
                                    ClientLocationType candidate_client_location)
        Determines if two individual ClientLocation nouns match each other for potential inclusion in the working set for the point of interest matching process.

        The default logic checks that the store ID, client ID, and source type match -- this means that the point of interest match process operates over all client location records for a given client ID (there may be multiple -- e.g. when visiting a shopping mall) which also match on the source type (e.g. "GPS") -- this allows the resolver to operate only over "GPS" records and leave other records for the client untouched.

        Custom logic may be provided by overriding this method -- for example, by removing the restriction that the source types match, ALL client location reports for a given client ID would be considered in the point of interest matching process.

        Specified by:
        clientLocationsMatch in interface ResolveClientLocationCmd
        Parameters:
        incoming_client_location - A client location noun which has been reported to the command either in the create list or the update list.

        candidate_client_location - A pre-existing client location noun which is a candidate for inclusion in the working set for the point of interest matching process.

        Returns:
        True if the candidate client location noun should be included in the working set for the point of interest matching process, false otherwise.

Skip navigation links