Criteria (ks 1.7.1 API)

java.lang.Object
- eu.fbk.knowledgestore.data.Criteria

All Implemented Interfaces:

Serializable
```
public abstract class Criteria
extends Object
implements Serializable
```
Merge criteria for combining old and new values of record properties.
A Criteria represents (a set of) merge criteria for combining old and new values of selected record properties. Merge criteria are specified when updating records in the KnowledgeStore via its API, and can be also used on their own for manipulating records on the client side.

The set of properties a Criteria object supports may be restricted. Method getProperties() returns this set; the result is empty if the Criteria object supports any property. Methods appliesTo(URI) and appliesToAll() can be conveniently used for testing whether a specific property or all possible properties are respectively supported by a given Criteria object.

Merging can be performed at two levels:
- on a single property, via method merge(URI, List, List) that returns the list produced by merging old and new values, without modifying its inputs;
- over multiple properties in common to a pair of records, via method merge(Record, Record); this method merges values of any property in common to the old and new record which is supported by the Criteria, storing the resulting values in the old record, which is thus modified in place; if modification of input parameters is not desired, the caller may clone the old record in advance and supply the clone to the merge() method.
The following Criteria are supported, and can be instantiated based on specific factory methods:
- overwrite criteria (factory method overwrite(URI...)), consisting in the discarding of old values which are overwritten with new values (even if new values are the empty list, which means the affected property is cleared);
- update criteria (factory method update(URI...)), consisting in the replacement of old values with new ones, but only if the list of new values is not empty (otherwise, old values are kept);
- init criteria (factory method init(URI...)), consisting in the assignment of new values only if the list of old values is empty, i.e., the property is initialized to the supplied of new values if previously unset, otherwise old values are kept;
- union criteria (factory method union(URI...)), consisting in computing and assigning the union of old and new values, removing duplicates (in which case the new value is kept, which for nested records means that properties of old nested records are discarded);
- min criteria (factory method min(URI...)), consisting in identifying and assigning the minimum value among the old and new ones (the comparator returned by Data.getTotalComparator() is used);
- max criteria (factory method max(URI...)), consisting in identifying and assigning the maximum value among the old and new ones (the comparator returned by Data.getTotalComparator() is used);
- composed criteria (factory method compose(Criteria...)), consisting in applying the first matching Criteria of the specified list to an input property; the resulting Criteria will be able to merge the union of all the properties supported by the composed Criteria. In case decomposition of a possibly composed Criteria is desired, method decompose() returns the (recursively) composed elementary Criteria for a certain input Criteria (the input Criteria is returned unchanged if not composes).
Criteria objects are immutable and thus thread safe. Two Criteria objects are equal if they implement the same strategy (possibly composed) and support the same properties. Serialization to string and deserialization back to a Criteria object are supported, via methods toString(), toString(Map) (which accepts a custom namespace map for encoding properties) and parse(String, Map). The string specification of a Criteria has the following form: criteria1 property11, ..., property1N, ..., criteriaM propertyM1, ... propertyMN where commas are all optional, the criteria token is one of overwrite, update, init, union, min, max (case does not matter) and properties are encoded according to the Turtle / TriG syntax (full URIs between < and > characters or QNames).
See Also:

Serialized Form

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`appliesTo(org.openrdf.model.URI property)` Checks whether the property specified is supported by this `Criteria` object.
`boolean`	`appliesToAll()` Checks whether all properties are supported by this `Criteria` object.
`static Criteria`	`compose(Criteria... criteria)` Creates a `Criteria` object that composes the `Criteria` objects specified in a composed merge criteria.
`List<Criteria>`	`decompose()` Decomposes this `Criteria` object in its elementary (i.e., non-composed) components.
`boolean`	`equals(Object object)` Two `Criteria` objects are equal if they implement the same merge criteria over the same properties.
`Set<org.openrdf.model.URI>`	`getProperties()` Returns the set of properties supported by this `Criteria` object.
`int`	`hashCode()` The returned hash code reflects the specific criteria and supported properties of this `Criteria` object.
`static Criteria`	`init(org.openrdf.model.URI... properties)` Creates a `Criteria` object implementing the init merge criteria for the properties specified.
`static Criteria`	`max(org.openrdf.model.URI... properties)` Creates a `Criteria` object implementing the max merge criteria for the properties specified.
`void`	`merge(Record oldRecord, Record newRecord)` Merges all supported properties in common to the old and new record specified, storing the results in the old record.
`List<Object>`	`merge(org.openrdf.model.URI property, List<? extends Object> oldValues, List<? extends Object> newValues)` Merges old and new values of the property specified, returning the resulting list of values.
`static Criteria`	`min(org.openrdf.model.URI... properties)` Creates a `Criteria` object implementing the min merge criteria for the properties specified.
`static Criteria`	`overwrite(org.openrdf.model.URI... properties)` Creates a `Criteria` object implementing the overwrite merge criteria for the properties specified.
`static Criteria`	`parse(String string, Map<String,String> namespaces)` Parses the supplied string specification of a merge criteria, returning the parsed `Criteria` object.
`String`	`toString()` This method returns a parseable string representation of this `Criteria` object, encoding property URIs as full, non-abbreviated URIs.
`String`	`toString(Map<String,String> namespaces)` Returns a parseable string representation of this `Criteria` object, using the supplied namespace map for encoding property URIs.
`static Criteria`	`union(org.openrdf.model.URI... properties)` Creates a `Criteria` object implementing the union merge criteria for the properties specified.
`static Criteria`	`update(org.openrdf.model.URI... properties)` Creates a `Criteria` object implementing the update merge criteria for the properties specified.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Method Detail
  - parse
```
public static Criteria parse(String string,
                             @Nullable
                             Map<String,String> namespaces)
                      throws ParseException
```
    Parses the supplied string specification of a merge criteria, returning the parsed Criteria object. The string must adhere to the format specified in the main Javadoc comment.
    
    Parameters:
    
    string - the specification of the merge criteria
    
    namespaces - the namespace map to be used for parsing the string, null if no mapping should be used
    
    Returns:
    
    the parsed Criteria, on success
    
    Throws:
    
    ParseException - in case the specification string is not valid
  - overwrite
```
public static Criteria overwrite(org.openrdf.model.URI... properties)
```
    Creates a Criteria object implementing the overwrite merge criteria for the properties specified. The overwrite criteria always selects the new values of a property, even if they consist in an empty list that will cause the property to be cleared.
    
    Parameters:
    
    properties - a vararg array with the properties over which the criteria should be applied; if empty, the criteria will be applied to any property
    
    Returns:
    
    the created Criteria object
  - update
```
public static Criteria update(org.openrdf.model.URI... properties)
```
    Creates a Criteria object implementing the update merge criteria for the properties specified. The update criteria assigns the new values to a property only if they do not consist in the empty list, in which case old values are kept.
    
    Parameters:
    
    properties - a vararg array with the properties over which the criteria should be applied; if empty, the criteria will be applied to any property
    
    Returns:
    
    the created Criteria object
  - init
```
public static Criteria init(org.openrdf.model.URI... properties)
```
    Creates a Criteria object implementing the init merge criteria for the properties specified. The init criteria assignes the new values to a property only if it has no old value (i.e., old values are the empty list), thus realizing a one-time property initialization mechanism.
    
    Parameters:
    
    properties - a vararg array with the properties over which the criteria should be applied; if empty, the criteria will be applied to any property
    
    Returns:
    
    the created Criteria object
  - union
```
public static Criteria union(org.openrdf.model.URI... properties)
```
    Creates a Criteria object implementing the union merge criteria for the properties specified. The union criteria assigns the union of old and new values to a property, discarding duplicates. In case duplicates are two nested records with the same ID (thus evaluating equal), the new value is kept.
    
    Parameters:
    
    properties - a vararg array with the properties over which the criteria should be applied; if empty, the criteria will be applied to any property
    
    Returns:
    
    the created Criteria object
  - min
```
public static Criteria min(org.openrdf.model.URI... properties)
```
    Creates a Criteria object implementing the min merge criteria for the properties specified. The min criteria assignes the minimum value among the old and new ones.
    
    Parameters:
    
    properties - a vararg array with the properties over which the criteria should be applied; if empty, the criteria will be applied to any property
    
    Returns:
    
    the created Criteria object
  - max
```
public static Criteria max(org.openrdf.model.URI... properties)
```
    Creates a Criteria object implementing the max merge criteria for the properties specified. The max criteria assignes the maximum value among the old and new ones.
    
    Parameters:
    
    properties - a vararg array with the properties over which the criteria should be applied; if empty, the criteria will be applied to any property
    
    Returns:
    
    the created Criteria object
  - compose
```
public static Criteria compose(Criteria... criteria)
```
    Creates a Criteria object that composes the Criteria objects specified in a composed merge criteria. Given a property whose old and new values have to be merged, the created composed criteria will scan through the supplied list of Criteria using the first matching one. As a consequence, the created criteria will support all the properties that are supported by at least one of the composed Criteria; if one of them supports all the properties, then the composed criteria will also support all the properties.
    
    Parameters:
    
    criteria - the Criteria objects to compose
    
    Returns:
    
    the created Criteria object
  - getProperties
```
public final Set<org.openrdf.model.URI> getProperties()
```
    Returns the set of properties supported by this Criteria object.
    
    Returns:
    
    a set with the supported properties; if empty, all properties are supported
  - appliesTo
```
public final boolean appliesTo(org.openrdf.model.URI property)
```
    Checks whether the property specified is supported by this Criteria object.
    
    Parameters:
    
    property - the property
    
    Returns:
    
    true, if the property is supported
  - appliesToAll
```
public final boolean appliesToAll()
```
    Checks whether all properties are supported by this Criteria object.
    
    Returns:
    
    true, if all properties are supported, with no restriction
  - merge
```
public final void merge(Record oldRecord,
                        Record newRecord)
```
    Merges all supported properties in common to the old and new record specified, storing the results in the old record.
    
    Parameters:
    
    oldRecord - the record containing old property values, not null; results of the merging operation are stored in this record, possibly replacing old values of affected properties (if this behavious is not desired, clone the old record in advance)
    
    newRecord - the record containing new property values, not null
  - merge
```
public final List<Object> merge(org.openrdf.model.URI property,
                                List<? extends Object> oldValues,
                                List<? extends Object> newValues)
```
    Merges old and new values of the property specified, returning the resulting list of values. Input value lists are not affected. In case the property specified is not supported by this Criteria object, the old list of values is returned.
    
    Parameters:
    
    property - the property to merge (used to control whether merging should be performed and which strategy should be adopted in case of a composed Criteria object)
    
    oldValues - a list with the old values of the property, not null
    
    newValues - a list with the new values of the property, not null
    
    Returns:
    
    the list of values obtained by applying the merge criteria
  - decompose
```
public final List<Criteria> decompose()
```
    Decomposes this Criteria object in its elementary (i.e., non-composed) components. In case this Criteria object is not composed, it is directly returned by the method in a singleton list. Otherwise, its components are recursively extracted and returned in a list that reflects their order of use.
    
    Returns:
    
    a list of non-composed Criteria objects, in the same order as they are applied in this merge criteria object
  - equals
```
public final boolean equals(Object object)
```
    Two Criteria objects are equal if they implement the same merge criteria over the same properties.
    
    Overrides:
    
    equals in class Object
  - hashCode
```
public final int hashCode()
```
    The returned hash code reflects the specific criteria and supported properties of this Criteria object.
    
    Overrides:
    
    hashCode in class Object
  - toString
```
public final String toString(@Nullable
                             Map<String,String> namespaces)
```
    Returns a parseable string representation of this Criteria object, using the supplied namespace map for encoding property URIs.
    
    Parameters:
    
    namespaces - the namespace map to encode property URIs
    
    Returns:
    
    the produced string
  - toString
```
public final String toString()
```
    This method returns a parseable string representation of this Criteria object, encoding property URIs as full, non-abbreviated URIs.
    
    Overrides:
    
    toString in class Object

Class Criteria

Method Summary

Methods inherited from class java.lang.Object

Method Detail

parse

overwrite

update

init

union

min

max

compose

getProperties

appliesTo

appliesToAll

merge

merge

decompose

equals

hashCode

toString

toString