eu.fbk.knowledgestore.data

Class Record

java.lang.Object

eu.fbk.knowledgestore.data.Record

All Implemented Interfaces:

Serializable, Comparable<Record>

public final class Record
extends Object
implements Serializable, Comparable<Record>

A record structure characterized by an ID and a generic set of properties.

A record is a structured identified by an URI ID and having a number of key-value properties, where the key is a URI and the value is a non-empty list of objects, which can be other Records, URIs, BNodes, Literals or Statements. Records are used to carry the data of resources, representations, mentions, entities, axioms, contexts and of any structured property value.

Records are created via factory methods create():

• method create() creates an empty record, without ID and properties;
• method create(URI, URI...) creates a new record with the ID and the types (values of property rdf:type supplied;
• method create(Record, boolean) creates a copy of a supplied method, possibly performing deep-cloning of its properties.

Record equality (equals(Object), hashCode()) is defined in terms of the record ID only, while toString() emits only the record type and ID. Beware that the ID can change during a Record lifetime (via method setID(URI)): this provides for increased flexibility, but pay attention not to change the ID when storing records in indexed data structure such as Sets and Maps, which rely on hashCode() and equals() to produce constant outcomes. Additional method #toString(boolean) allows for emitting a complete record representation including its properties, while equality of (selected) properties in different records can be checked by comparing the respective hashes, computed via hash(URI...); the same hash() method can help in creating syntetic IDs based on the values of some properties (e.g., following a pattern PREFIX + record.hash(p1, p2, ...).

Access to and manipulation of properties is performed as follows:

• Listing available properties. Method getProperties() returns the list of properties having some value for a record instance.
• Reading properties. The main method is get(URI), which is complemented by a number of auxiliary methods for ease of use. They are described below:
  • get(URI), get(URI, Class) and get(URI, Class, List) allow retrieving all the values of a specific property, either as a list of objects or converted to a specific target class; the last methed supports also the specification of a default value, which is returned if the property has no values or if conversion fails.
  • getUnique(URI), getUnique(URI, Class), getUnique(URI, Class, Object) allow retrieving the unique value of a property, either as an object or converted to a specific class; unless a default value is specified, the methods fail in case multiple values are associated to the property, thus helping enforcing the uniqueness expectation.
  • isTrue(URI), isFalse(URI) are convenience methods that can be used for boolean properties; they fail if used on properties having multiple or non-boolean values.
  • isNull(URI), isUnique(URI) are convenience methods that can be used to test whether a property has at least or at most one value.
  • count(URI) is a convenience method for counting the values of a property; it may be faster than using get().
• Modifying properties. Two types of methods are offered:
  • modification of individual properties is done via set(URI, Object, Object...), add(URI, Object, Object...) and remove(URI, Object, Object...), that allow, respectively, to set all the values of a property, to add some new values to a property or to remove existing values from the values of a property. For ease of use, these methods accept (at least) an argument object which can be a Record, URI, BNode, Statement, Literal, an object convertible to Literal or any array or iterable of the former types. A list of values is extracted from the supplied objects, and used for modifying the values of the property.
  • modification of multiple properties at once is done via clear(URI...) and retain(URI...), which remove all the properties respectively matching or not matching a supplied list, allowing as a special case (no properties specified) to remove all the properties of a record instance.

Instances of this interface are thread safe. Cloning of record instances (via create(Record, boolean)) is supported and is a relatively inexpensive operation; a copy-on-write approach is adopted to reduce the memory usage of cloned objects, which share their state with the source object as long as one of the two is changed.

See Also:

Serialized Form

Method Summary

Modifier and Type	Method and Description
Record	add(org.openrdf.model.URI property, Object first, Object... other) Adds one or more values to the property specified.
Record	clear(org.openrdf.model.URI... properties) Clears the properties specified, or all the stored properties if no property is specified.
int	compareTo(Record other) Comparison is based on the record IDs only.
int	count(org.openrdf.model.URI property) Returns the number of values assigned to the property specified.
static Record	create() Creates a new record with no properties and ID assigned.
static Record	create(Record record, boolean deepClone) Creates a new record having the same ID and properties of the supplied record, possibly performing a deep-cloning (copy constructor).
static Record	create(org.openrdf.model.URI id, org.openrdf.model.URI... types) Creates a new record with the ID and the types specified (property rdf:type), and no additional properties.
static Stream<Record>	decode(Stream<org.openrdf.model.Statement> stream, Iterable<? extends org.openrdf.model.URI> types, Boolean chunked) Performs RDF-to-record decoding by converting a stream of RDF statements in a stream of records.
static Stream<org.openrdf.model.Statement>	encode(Stream<? extends Record> stream, Iterable<? extends org.openrdf.model.URI> types) Performs record-to-RDF encoding by converting a stream of records in a stream of RDF statements.
boolean	equals(Object object) Two records are equal if they have the same IDs.
List<Object>	get(org.openrdf.model.URI property) Returns the Object values of the property specified.
<T> List<T>	get(org.openrdf.model.URI property, Class<T> valueClass) Returns the values of the property converted to instances of a certain class.
<T> List<T>	get(org.openrdf.model.URI property, Class<T> valueClass, List<T> defaultValue) Returns the values of the property converted to instances of a certain class, or the default value supplied in case of failure or if the property has no values.
org.openrdf.model.URI	getID() Returns the ID of this record.
List<org.openrdf.model.URI>	getProperties() Returns all the properties currently defined for this record.
org.openrdf.model.URI	getSystemType() Returns the system type for this record, i.e., the rdf:type URI under the ks: namespace, if any.
Object	getUnique(org.openrdf.model.URI property) Returns the unique Object value of a property, or null if it has no value.
<T> T	getUnique(org.openrdf.model.URI property, Class<T> valueClass) Returns the unique value of the property converted to an instance of a certain class, or null if the property has no value.
<T> T	getUnique(org.openrdf.model.URI property, Class<T> valueClass, T defaultValue) Returns the unique value of the property converted to an instance of a certain class, or the default value supplied in case of failure.
String	hash(org.openrdf.model.URI... properties) Computes a string-valued hash code of the properties specified, or of all the available properties, if no URI is specified.
int	hashCode() The returned hash code depends only on the record ID.
boolean	isFalse(org.openrdf.model.URI property) Determines whether the property specified has been set to false.
boolean	isNull(org.openrdf.model.URI property) Determines whether the property specified is null, i.e., it has no value.
boolean	isTrue(org.openrdf.model.URI property) Determines whether the property specified has been set to true.
boolean	isUnique(org.openrdf.model.URI property) Determines whether the property specified has at most one value.
Record	remove(org.openrdf.model.URI property, Object first, Object... other) Removes one or more values from the property specified.
Record	retain(org.openrdf.model.URI... properties) Retains only the properties specified, clearing the remaining ones.
Record	set(org.openrdf.model.URI property, Object first, Object... other) Sets the values of the property specified.
Record	setID(org.openrdf.model.URI id) Sets the ID of this record.
String	toString() The returned string contains only the ID of the record.
String	toString(Map<String,String> namespaces, boolean includeProperties) Returns a string representation of the record, optionally using the namespaces supplied and emitting record properties.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

create

public static Record create()

Creates a new record with no properties and ID assigned.

Returns:

the created record

create

public static Record create(org.openrdf.model.URI id,
                            org.openrdf.model.URI... types)

Creates a new record with the ID and the types specified (property rdf:type), and no additional properties.

Parameters:

id - the ID of the new record, possibly null in order not to assign it

types - the types of the record, assigned to property rdf:type

Returns:

the created record

create

public static Record create(Record record,
                            boolean deepClone)

Creates a new record having the same ID and properties of the supplied record, possibly performing a deep-cloning (copy constructor). The difference between shallow- and deep-cloning lies in the handling of property values of Record type, which are shared by the source and cloned object in case of shallow-cloning, and cloned themselves in case of deep-cloning.

Parameters:

record - the reference record to clone

deepClone - true to perform a deep-cloning, false to perform a shallow-cloning

Returns:

the created record clone

getID

@Nullable
public org.openrdf.model.URI getID()

Returns the ID of this record.

Returns:

the ID of this record, possibly null if not previously assigned

setID

public Record setID(@Nullable
                    org.openrdf.model.URI id)

Sets the ID of this record.

Parameters:

id - the new ID of this record or null to clear it

Returns:

this record object, for call chaining

getSystemType

@Nullable
public org.openrdf.model.URI getSystemType()
                                              throws IllegalArgumentException

Returns the system type for this record, i.e., the rdf:type URI under the ks: namespace, if any.

Returns:

the system type or null if not set

Throws:

IllegalArgumentException - in case multiple system types are bound to the record

getProperties

public List<org.openrdf.model.URI> getProperties()

Returns all the properties currently defined for this record.

Returns:

an immutable list with the properties currently defined for this record, without repetitions and in no particular order

isNull

public boolean isNull(org.openrdf.model.URI property)

Determines whether the property specified is null, i.e., it has no value.

Parameters:

property - the property to read

Returns:

true if the property has no value

isUnique

public boolean isUnique(org.openrdf.model.URI property)

Determines whether the property specified has at most one value.

Parameters:

property - the property to read

Returns:

true if the property has at most value; false if it has multiple values

isTrue

public boolean isTrue(org.openrdf.model.URI property)
               throws IllegalStateException,
                      IllegalArgumentException

Determines whether the property specified has been set to true. The method fails if the property has multiple values or has a non-boolean type; if this behaviour is not desired, use getUnique(URI, Class, Object) specifying Boolean.class as the class and an appropriate default value to be returned in case of failure.

Parameters:

property - the property to read

Returns:

true if the property is set to true; false if the property has no value or has been set to false

Throws:

IllegalStateException - in case the property has multiple values

IllegalArgumentException - in case the property value is not of boolean type

isFalse

public boolean isFalse(org.openrdf.model.URI property)
                throws IllegalStateException,
                       IllegalArgumentException

Determines whether the property specified has been set to false. The method fails if the property has multiple values or has a non-boolean type; if this behaviour is not desired, use getUnique(URI, Class, Object) specifying Boolean.class as the class and an appropriate default value to be returned in case of failure.

Parameters:

property - the property to read

Returns:

true if the property is set to false; false if the property has no value or has been set to true

Throws:

IllegalStateException - in case the property has multiple values

IllegalArgumentException - in case the property value is not of boolean type

count

public int count(org.openrdf.model.URI property)

Returns the number of values assigned to the property specified. Calling this method may be faster that using get(URI).

Parameters:

property - the property

Returns:

the number of values

getUnique

@Nullable
public Object getUnique(org.openrdf.model.URI property)
                           throws IllegalStateException

Returns the unique Object value of a property, or null if it has no value. Note that this method fails if the property has multiple values; if this is not the desired behaviour, use getUnique(URI, Class, Object) supplying an appropriate type (could be Object.class) and default value to be returned in case of failure.

Parameters:

property - the property to read

Returns:

the unique Object value of the property; null if it has no value

Throws:

IllegalStateException - in case the property has multiple values

getUnique

@Nullable
public <T> T getUnique(org.openrdf.model.URI property,
                                 Class<T> valueClass)
                          throws IllegalStateException,
                                 IllegalArgumentException

Returns the unique value of the property converted to an instance of a certain class, or null if the property has no value. Note that this method fails if the property has multiple values or its unique value cannot be converted to the requested class; if this is not the desired behavior, use getUnique(URI, Class, Object) supplying an appropriate default value to be returned in case of failure.

Type Parameters:

T - the type of result

Parameters:

property - the property to read

valueClass - the class to convert the value to

Returns:

the unique value of the property, converted to the class specified; null if the property has no value

Throws:

IllegalStateException - in case the property has multiple values

IllegalArgumentException - in case the unique property value cannot be converted to the class specified

getUnique

@Nullable
public <T> T getUnique(org.openrdf.model.URI property,
                                 Class<T> valueClass,
                                 @Nullable
                                 T defaultValue)

Returns the unique value of the property converted to an instance of a certain class, or the default value supplied in case of failure.

Type Parameters:

T - the type of result

Parameters:

property - the property to read

valueClass - the class to convert the value to

defaultValue - the default value to return in case the property has no value

Returns:

the unique value of the property converted to the class specified, on success; the default value supplied in case the property has no value, has multiple values or its unique value cannot be converted to the class specified

get

public List<Object> get(org.openrdf.model.URI property)

Returns the Object values of the property specified.

Parameters:

property - the property to read

Returns:

an immutable list with the Object values of the property, without repetitions, in no particular order and possibly empty

get

public <T> List<T> get(org.openrdf.model.URI property,
                       Class<T> valueClass)
                throws IllegalArgumentException

Returns the values of the property converted to instances of a certain class. Note that this method fails if conversion is not possible for one or more of the property values; if this is not the desired behavior, use get(URI, Class, List) specifying an appropriate default value to be returned in case of conversion failure.

Type Parameters:

T - the type of property values

Parameters:

property - the property to read

valueClass - the class values have to be converted to

Returns:

an immutable list with the values of the property, converted to the class specified, possibly empty

Throws:

IllegalArgumentException - in case one of the property values cannot be converted to the class specified

get

public <T> List<T> get(org.openrdf.model.URI property,
                       Class<T> valueClass,
                       List<T> defaultValue)

Returns the values of the property converted to instances of a certain class, or the default value supplied in case of failure or if the property has no values.

Type Parameters:

T - the type of property values

Parameters:

property - the property to read

valueClass - the class values have to be converted to

defaultValue - the default value to return in case conversion fails

Returns:

an immutable list with the values of the property, converted to the class specified and possibly empty, on success; the default value supplied in case the property has no value or conversion fails for some value

set

public Record set(org.openrdf.model.URI property,
                  @Nullable
                  Object first,
                  Object... other)
           throws IllegalArgumentException

Sets the values of the property specified. The method accepts one or more objects as the values; these objects can be Records, URIs, BNodes, Statements, Literals, objects convertible to Literal or any array or iterable of the former types. Setting a property to null has the effect of clearing it.

Parameters:

property - the property to set

first - the first value, array or iterable of values to set, possibly null

other - additional values, arrays or iterables of values to set (if specified, will be merged with first).

Returns:

this record object, for call chaining

Throws:

IllegalArgumentException - if one of the supplied values has an unsupported type

add

public Record add(org.openrdf.model.URI property,
                  @Nullable
                  Object first,
                  Object... other)
           throws IllegalArgumentException

Adds one or more values to the property specified. The method accepts one or more objects as the values; these objects can be Records, URIs, BNodes, Statements, Literals, objects convertible to Literal or any array or iterable of the former types.

Parameters:

property - the property to modify

first - the first value, array or iterable of values to add, possibly null

other - additional values, arrays or iterables of values to set (if specified, will be merged with first).

Returns:

this record object, for call chaining

Throws:

IllegalArgumentException - if one of the supplied values has an unsupported type

remove

public Record remove(org.openrdf.model.URI property,
                     @Nullable
                     Object first,
                     Object... other)
              throws IllegalArgumentException

Removes one or more values from the property specified. The method accepts one or more objects as the values; these objects can be Records, URIs, BNodes, Statements, Literals, objects convertible to Literal or any array or iterable of the former types.

Parameters:

property - the property to modify

first - the first value, array or iterable of values to remove, possibly null

other - additional values, arrays or iterables of values to remove (if specified, will be merged with first).

Returns:

this record object, for call chaining

Throws:

IllegalArgumentException - if one of the supplied values has an unsupported type

retain

public Record retain(org.openrdf.model.URI... properties)

Retains only the properties specified, clearing the remaining ones. Note that the ID is not affected.

Parameters:

properties - an array with the properties to retain, possibly empty (in which case all the stored properties will be cleared)

Returns:

this record object, for call chaining

clear

public Record clear(org.openrdf.model.URI... properties)

Clears the properties specified, or all the stored properties if no property is specified. Note that the ID is not affected.

Parameters:

properties - an array with the properties to retain, possibly empty (in which case all the stored properties will be cleared)

Returns:

this record object, for call chaining

compareTo

public int compareTo(Record other)

Comparison is based on the record IDs only.

Specified by:

compareTo in interface Comparable<Record>

equals

public boolean equals(Object object)

Two records are equal if they have the same IDs.

Overrides:

equals in class Object

hashCode

public int hashCode()

The returned hash code depends only on the record ID.

Overrides:

hashCode in class Object

hash

public String hash(org.openrdf.model.URI... properties)

Computes a string-valued hash code of the properties specified, or of all the available properties, if no URI is specified. Order of selected properties and order of values of each property do not matter. A cryptographic hash function is used. Collision probability is negligible. This method can be used to check whether two records have the same (subsets of) properties, by computing and comparing the respective hashes.

Parameters:

properties - the properties to hash.

Returns:

the computed hash code

toString

public String toString(@Nullable
                       Map<String,String> namespaces,
                       boolean includeProperties)

Returns a string representation of the record, optionally using the namespaces supplied and emitting record properties. This method extends #toString(), optionally allowing to emit also record properties and, recursively, properties of records nested in this record.

Parameters:

namespaces - the prefix-to-namespace mappings to be used when emitting property and value URIs; if null, only non-abbreviated, full URIs will be emitted

includeProperties - true if record properties should be emitted too

Returns:

a string representation of the record, computed based on the includeProperties setting

toString

public String toString()

The returned string contains only the ID of the record.

Overrides:

toString in class Object

encode

public static Stream<org.openrdf.model.Statement> encode(Stream<? extends Record> stream,
                                                         @Nullable
                                                         Iterable<? extends org.openrdf.model.URI> types)

Performs record-to-RDF encoding by converting a stream of records in a stream of RDF statements. Parameter types specify additional types to be added to encoded records. Type information may be set to null (e.g., because unknown at the time the method is called): in this case, it will be read from metadata attribute "types" attached to the stream; reading will happen just before decoding will take place, i.e., when a terminal stream operation will be called.

Parameters:

stream - the stream of records to encode.

types - the types to be added to each record of the stream, null if to be read from stream metadata

Returns:

the resulting stream of statements

decode

public static Stream<Record> decode(Stream<org.openrdf.model.Statement> stream,
                                    @Nullable
                                    Iterable<? extends org.openrdf.model.URI> types,
                                    @Nullable
                                    Boolean chunked)

Performs RDF-to-record decoding by converting a stream of RDF statements in a stream of records. Parameter types specify the types of records that have to be extracted from the statement stream, while parameter chunked specifies whether the input statement stream is chunked, i.e., organized as a sequence of statement chunks with each chunk containing the statements for a record (and its nested records). Chunked RDF streams noticeably speed up decoding, and are always produced by the KnowledgeStore API. Type and chunking information may be set to null (e.g., because unknown at the time the method is called): in this case, they will be read from metadata attributes attached to the stream, named "types" and "chunked"; reading will happen just before decoding will take place, i.e., when a terminal stream operation will be called.

Parameters:

stream - the stream of statements to decode

types - the types of records to extract from the statement stream, null if to be read from stream metadata

chunked - true if the input statement stream is chunked, null if to be read from stream metadata

Returns:

the resulting stream of records