Package de.dlr.proseo.model.util

Klasse SelectionRule

java.lang.Object
de.dlr.proseo.model.util.SelectionRule
public class SelectionRule extends Object
This class allows to describe temporal selection policies for item types, to manipulate selection policies (combining and chaining), to select valid items from a container of items, and to generate product query objects from a selection rule (the result of the product query can then be fed into the item selection method to filter the actually valid items).

A selection rule can be described in text form according to the following grammar (words in single quotes denote language key words, angled brackets denote optional elements, an ellipsis denotes zero or more repetitions of the element preceding it, a vertical bar denotes choice between two or more elements, all other punctuation characters are to be taken literally): 

 rule ::= simple_rule [ ; rule ]
 simple_rule ::= 'FOR' source_product_type 'SELECT' policy [ 'OPTIONAL' | 'MANDATORY' | 'MINCOVER' ( digit ... ) ]
 policy ::= simple_policy [ 'OR' policy ]
 simple_policy ::= policy_name [ ( delta_time , delta_time ) ]
 policy_name ::= 'ValCover' | 'LatestValCover' | 'ValIntersect' | 'latestValIntersect' | 'LatestValidityClosest' |
                 'BestCenteredCover' | 'LatestValCoverClosest' | 'LargestOverlap' | 'LargestOverlap85' | 
                 'LatestValidity' | 'LatestValCoverNewestValidity' | 'ClosestStartValidity' | 'ClosestStopValidity' |
                 'LatestStartValidity' | 'LatestStopValidity' | 'ValIntersectWithoutDuplicates' | 'LastCreated'
 source_product_type ::= product_type[/parameter_key:parameter_value[,parameter_key:parameter_value] ...] 
 delta_time ::= digit ... [ 'd' | 'h' | 'm' | 's' | 'ms' ]
 digit ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
Key words are not case sensitive, this includes the names of selection policies. Punctuation characters need not (but may) be enclosed by white space.

If for a simple rule neither OPTIONAL nor MINCOVER or MANDATORY is specified, MANDATORY is the default. If for a delta time, neither 'd' (days), 'h' (hours), 'm' (minutes), 's' (seconds) or 'ms' (microseconds) is specified, 'd' (days) is the default.

A simple rule marked as OPTIONAL is fulfilled even if no items satisfy the rule. For a simple rule marked MANDATORY at least one item must fulfil the rule criteria. If the rule is marked as MINCOVER(n), the set of items fulfilling the rule criteria must as a whole cover at least n % of the validity interval given as selection parameters. MINCOVER implies MANDATORY (even MINCOVER(0), in which case it is acceptable, if all items are outside of the validity interval).

The 'OR' operator is a short-circuited operator, i. e. if during the selection of items the first simple policy yields a non-empty result set, this result set is returned, and only if the result set is empty, the policy following the 'OR' is evaluated.

Multiple occurrences of 'LatestValidityClosest' for the same item type (product type) in one set of selection rules are only allowed, if all occurrences have the same delta times. (This policy actually refers to a point in time and not to a time interval, therefore a merge can only be done between policies referring to the same point in time.)

A 'source_product_type' consists of prosEO product (class) type and optionally parameter values to filter items within the collection. Parameter keys and values are separated from the product type by a slash ('/'), and are separated from each other by commas. Parameter key and value for each entry are separated by colons (':'). There must not be any white space between any of the elements of the product type. Note that for the purpose of the selection, source product types with the same product type name, but different parameters are considered different source product types. The parameter keys and values are only evaluated for the generation of JPQL and SQL queries.

The following are examples for legal rules:

  • FOR AUX_CH4 SELECT ValIntersect(0, 0)
  • FOR AUX_CH4 SELECT ValIntersect(0, 0) OR LatestValidity
  • FOR AUX_CH4 SELECT ValIntersect(0, 0) OR LatestValidity OPTIONAL; for AUX_ECMWF-FC48 select latestvalintersect ( 12 h , 24 h )
Note that in the last example, the name of the product type is in upper case, although the keywords are not. Product type names are case sensitive!

The following rule examples are not valid:

  • SELECT ValIntersect(0, 0) (the auxiliary product type must be specified)
  • FOR AUX_CH4 SELECT ValIntersect(-1, 0) (no negative values)
  • FOR AUX_CH4 SELECT ValIntersect(1h, 1h) (the time unit must be separated from the numerical value by white space)
  • FOR AUX_CH4 SELECT ValIntersect(0, 0); (the semicolon is a rule separator, not a rule terminator)
Allowed selection policies are described in ESA's "Generic IPF Interface Specification" (MMFI-GSEG-EOPG-TN-07-0003, issue 1.8), applicable product types are mission-specific and defined by the available product classes (attribute productType) for the respective mission.

Autor:
Dr. Thomas Bassler

  • Felddetails

  • Konstruktordetails

    • SelectionRule

      public SelectionRule()

  • Methodendetails

    • getSimpleRules

      public List<SimpleSelectionRule> getSimpleRules()
      Gets all simple selection rules contained in the selection rule
      Gibt zurück:
      a list of simple selection rules

    • clearSimpleRules

      public void clearSimpleRules()
      Removes all simple selection rules from this rule

    • addSimpleRules

      public void addSimpleRules(Collection<SimpleSelectionRule> newSimpleRules)
      Adds a collection of simple selection rules to this rule
      Parameter:
      newSimpleRules - the collection of simple selection rules to add

    • setSimpleRules

      public void setSimpleRules(Collection<SimpleSelectionRule> simpleRules)
      Sets the collection of simple selection rules for this rule
      Parameter:
      simpleRules - the collection of simple selection rules to set

    • parseSelectionRule

      public static SelectionRule parseSelectionRule(ProductClass targetProductClass, String selectionRuleString) throws ParseException, IllegalArgumentException
      Parse the given string as a selection rule (see the grammar definition in the class comment). Returns a new instance of SelectionRule.
      Parameter:
      targetProductClass - the product class, which requires this rule for processing
      selectionRuleString - the string containing the selection rule
      Gibt zurück:
      a new SelectionRule object
      Löst aus:
      ParseException - if the string does not conform to the grammar given in the class comment
      IllegalArgumentException - if selectionRuleString is null

    • hasPolicyFor

      public Boolean hasPolicyFor(String itemType)
      Tests whether this rule has a selection policy for the given item type (aux product type)
      Parameter:
      itemType - the item type to test for
      Gibt zurück:
      true, if a policy for the item type exists, false otherwise

    • merge

      public SelectionRule merge(SelectionRule anotherRule) throws IllegalArgumentException
      Merge this selection rule with another selection rule, thereby extending the validity periods per product type for each policy in such a way that the validity periods of this rule and of the other rule are covered. This method returns a new SelectionRule object, the current object remains unchanged.

      For selection rules containing the policy 'LatestValidityClosest' a merge is possible, if and only if all occurrences of this policy for one product type in both rules have the same delta times (this policy actually refers to a point in time and not to a time interval, therefore a merge can only be done between policies referring to the same point in time).

      Parameter:
      anotherRule - the selection rule to merge this rule with
      Gibt zurück:
      a new SelectionRule object reflecting the merged validity periods for each policy of both rules
      Löst aus:
      IllegalArgumentException - if a merge between rules with 'LatestValidityClosest' policies with differing delta times for the same product type is attempted

    • selectUniqueItem

      public Object selectUniqueItem(String productType, Collection<SelectionItem> items, Instant startTime, Instant stopTime) throws NoSuchElementException, IllegalArgumentException
      Select the one item in the given collection of items that fulfils the selection rule with respect to a given time interval. All items in the collection must be of the same item product type. If the rule does not contain policies for the item type given in the collection, the result is the same as if all items had qualified (i. e. if the collection contains only one item, its object is returned, if it contains more than one item, NoSuchElementException is thrown).
      Parameter:
      productType - the product type of the items
      items - the collection of items to be searched
      startTime - the start time of the time interval to check against
      stopTime - the end time of the time interval to check against
      Gibt zurück:
      the single item object fulfilling the selection rule, if exactly one such item exists, or null, if no qualifying item exists and the selection rule is marked as 'OPTIONAL'
      Löst aus:
      NoSuchElementException - if there is more than one item fulfilling the selection rule, or if there is no such item and the selection rule is marked as 'MANDATORY'
      IllegalArgumentException - if any of the parameters is null or if not all of the items are of the given type

    • selectUniqueProduct

      public Product selectUniqueProduct(String productType, Collection<Product> products, Instant startTime, Instant stopTime) throws NoSuchElementException, IllegalArgumentException
      Select the one product in the given collection of products that fulfils the selection rule with respect to a given time interval. All products in the collection must be of the same product type. If the rule does not contain policies for the product type given in the collection, the result is the same as if all items had qualified (i. e. if the collection contains only one item, its object is returned, if it contains more than one item, NoSuchElementException is thrown).
      Parameter:
      productType - the product type of the items
      products - the collection of products to be searched
      startTime - the start time of the time interval to check against
      stopTime - the end time of the time interval to check against
      Gibt zurück:
      the single item object fulfilling the selection rule, if exactly one such item exists, or null, if no qualifying item exists and the selection rule is marked as 'OPTIONAL'
      Löst aus:
      NoSuchElementException - if there is more than one item fulfilling the selection rule, or if there is no such item and the selection rule is marked as 'MANDATORY'
      IllegalArgumentException - if any of the parameters is null or if not all of the items are of the given type

    • selectItems

      public List<Object> selectItems(String productType, Collection<SelectionItem> items, Instant startTime, Instant stopTime) throws NoSuchElementException, IllegalArgumentException
      Select all items in the given collection of items that fulfil the selection rule with respect to a given time interval. All items in the collection must be of the same item product type. If the rule does not contain policies for the item type given in the collection, an empty list returned.
      Parameter:
      productType - the type of the items to be searched
      items - the collection of items to be searched (may be empty, but not null)
      startTime - the start time of the time interval to check against
      stopTime - the end time of the time interval to check against
      Gibt zurück:
      a (possibly empty) list of all item objects fulfilling the selection rule, or null, if no such qualifying item exists and the selection rule is marked as 'OPTIONAL'
      Löst aus:
      NoSuchElementException - if no item fulfils the selection rule, and the selection rule is marked as 'MANDATORY'
      IllegalArgumentException - if any of the parameters is null or if not all of the items are of the given item type

    • selectProducts

      public List<Product> selectProducts(String productType, Collection<Product> products, Instant startTime, Instant stopTime) throws NoSuchElementException, IllegalArgumentException
      Select all products in the given collection of products that fulfil the selection rule with respect to a given time interval. All products in the collection must be of the same product type. If the rule does not contain policies for the product type given in the collection, an empty list returned.
      Parameter:
      productType - the type of the items to be searched
      products - the collection of products to be searched (may be empty, but not null)
      startTime - the start time of the time interval to check against
      stopTime - the end time of the time interval to check against
      Gibt zurück:
      a (possibly empty) list of all item objects fulfilling the selection rule, or null, if no such qualifying item exists and the selection rule is marked as 'OPTIONAL'
      Löst aus:
      NoSuchElementException - if no item fulfils the selection rule, and the selection rule is marked as 'MANDATORY'
      IllegalArgumentException - if any of the parameters is null or if not all of the items are of the given item type

    • toString

      public String toString()
      Setzt außer Kraft:
      toString in Klasse Object