eu.fbk.knowledgestore.data

Class Data

java.lang.Object

eu.fbk.knowledgestore.data.Data

public final class Data
extends Object

Helper services for working with KnowledgeStore data.

This class provides a number of services for working with KnowledgeStore data, i.e., with Representation, Value, Statement, Record instances and instances of scalar types that can be converted to Literal values. The following services are offered:

• MIME type registry. Method extensionToMimeType(String) and mimeTypeToExtensions(String) allow to map from a file extension to the corresponding MIME type and the other way round based on an internal database; in addition, method isMimeTypeCompressible(String) checks whether data of a MIME type can be effectively compressed. MIME types and associated extensions have been imported from the Apache Web server media type database (http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/conf/mime.types?view=markup). A list of non-compressed media types have been obtained from here: http://pic.dhe.ibm.com/infocenter/storwize/unified_ic/index.jsp?topic=%2Fcom.ibm.storwize. v7000.unified.140.doc%2Fifs_plancompdata.html. Some manual modification to the data has been done as well, with to goal to enforce that a file association is mapped to at most a media type (a few entries from the Apache DB had to be changed).
• Factories for value objects. Method getValueFactory() returns a singleton, memory-optimized ValueFactory for creating Statements and Values ( URIs, BNodes, Literals); method getDatatypeFactory() returns a singleton factory for creating instances of XML Schema structured types, such as XMLGregorianCalendar instances.
• Total and partial ordering. Methods getTotalComparator() and getPartialComparator() returns two general-purpose comparators that impose, respectively, a total and a partial order over objects of the data model. The total order allow comparing any pair of Values, Statements, Records and scalars convertible to literal values; resorting to type comparison if the denoted value belong to incomparable domains. The partial order compares only instances of compatible types (e.g., numbers with numbers), and can thus be better suited for the evaluation of conditions (while the total order can help with the presentation of data).
• Prefix-to-namespace mappings management support. Method getNamespaceMap() returns a prefix-to-namespace map with common bindings as defined on the prefix.cc site (as of end 2013); it can be used to achieve a reasonable presentation of URIs, e.g., for RDF serialization. Methods newNamespaceMap() and newNamespaceMap(Map, Map) create either an empty, optimized prefix-to-namespace map or a combined prefix-to-namespace map that merges definitions of two input maps. Method namespaceToPrefix(String, Map) performs a reverse lookup in a prefix-to-namespace map, efficiently returning the prefix for a given namespace.
• General-purpose conversion. Methods convert(Object, Class) and convert(Object, Class, Object) attempts conversion from a data model object to another data model class or scalar class compatible convertible to a literal object. More details about the conversion are specified in the associated Javadoc documentation.
• Value normalization. Methods normalize(Object) and normalize(Object, Collection) accepts any object of a data model class or of a scalar class convertible to a scalar literal (e.g., an integer) and normalize it to an instance of the three data model classes: Value, Statement and Record.
• String rendering and parsing. Methods toString(Object, Map) and toString(Object, Map, boolean) generate a string representation of any data model object, using the supplied prefix-to-namespace mappings and possibly including a full listing of record properties. Method parseValue(String, Map) allow parsing a Value out of a Turtle / TriG string, such as the ones produced by toString(...) methods.

TODO: this class needs urgent refactoring

Method Summary

Modifier and Type	Method and Description
static String	cleanIRI(String string) Clean an illegal IRI string, trying to make it legal (as per RFC 3987).
static String	cleanURI(String string) Clean a possibly illegal URI string (in a way similar to what a browser does), returning the corresponding cleaned URI object if successfull.
static <T> T	convert(Object object, Class<T> clazz) General conversion facility.
static <T> T	convert(Object object, Class<T> clazz, T defaultValue) General conversion facility, with fall back to default value.
static String	extensionToMimeType(String fileNameOrExtension) Returns the MIME type for the file extension specified, if known.
static DatatypeFactory	getDatatypeFactory() Returns a DatatypeFactory for creating XMLGregorianCalendar instances and instances of other XML schema structured types.
static ListeningScheduledExecutorService	getExecutor() Returns the executor shared by KnowledgeStore components.
static Map<String,String>	getNamespaceMap() Returns a map of common prefix-to-namespace mappings, taken from a prefix.cc dump.
static Comparator<Object>	getPartialComparator() Returns a comparator imposing a partial order over objects of the data model (Value s, Statements, Records).
static Comparator<Object>	getTotalComparator() Returns a comparator imposing a total order over objects of the data model (Values, Statements, Records).
static org.openrdf.model.ValueFactory	getValueFactory() Returns an optimized ValueFactory for creating RDF URIs, BNodes, Literals and Statements.
static String	hash(Object... objects) Utility method to compute an hash string from a vararg list of objects.
static boolean	isMimeTypeCompressible(String mimeType) Checks whether the specific MIME type can be compressed.
static org.openrdf.model.URI	languageCodeToURI(String code) Returns the language URI for the ISO 639 code (2-letters, 3-letters) specified.
static String	languageURIToCode(org.openrdf.model.URI uri) Returns the 2-letter ISO 639 code for the language URI supplied.
static List<String>	mimeTypeToExtensions(String mimeType) Returns the file extensions commonly associated to the specified MIME type.
static String	namespaceToPrefix(String namespace, Map<String,String> namespaceMap) Performs a reverse lookup of the prefix corresponding to a namespace in a prefix-to-namespace map.
static Map<String,String>	newNamespaceMap() Creates a new, empty prefix-to-namespace map that supports fast reverse prefix lookup via namespaceToPrefix(String, Map).
static Map<String,String>	newNamespaceMap(Map<String,String> primaryNamespaceMap, Map<String,String> secondaryNamespaceMap) Creates a new prefix-to-namespace map combining the mappings in the supplied maps.
static Object	normalize(Object object) Normalizes the supplied object to an object of the data model.
static boolean	normalize(Object object, Collection<Object> collection) Normalizes the supplied object to zero or more objects of the data model, which are added to the collection specified.
static org.openrdf.model.Value	parseValue(String string, Map<String,String> namespaces) Parses an RDF value out of a string.
static void	setExecutor(ScheduledExecutorService newExecutor) Setup the executor shared by KnowledgeStore components.
static String	toString(Object object, Map<String,String> namespaces) Returns a string representation of the supplied data model object, optionally using the supplied namespaces.
static String	toString(Object object, Map<String,String> namespaces, boolean includeProperties) Returns a string representation of the supplied data model object, optionally using the supplied namespaces and including record properties.
static void	validateIRI(String string) Check that the supplied string is a legal IRI (as per RFC 3987).

Methods inherited from class java.lang.Object

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

Method Detail

getExecutor

public static ListeningScheduledExecutorService getExecutor()

Returns the executor shared by KnowledgeStore components. If no executor is setup using setExecutor(ScheduledExecutorService), an executor is automatically created using the thread number and naming given by system properties eu.fbk.knowledgestore.threadCount and eu.fbk.knowledgestore.threadNumber.

Returns:

the shared executor

setExecutor

public static void setExecutor(ScheduledExecutorService newExecutor)

Setup the executor shared by KnowledgeStore components. If another executor was previously in use, it will not be used anymore; in case it was the executor automatically created by the system, it will be shutdown.

Parameters:

newExecutor - the new executor

getValueFactory

public static org.openrdf.model.ValueFactory getValueFactory()

Returns an optimized ValueFactory for creating RDF URIs, BNodes, Literals and Statements. Note that while any ValueFactory can be used for this purpose (including the ValueFactoryImpl shipped with Sesame), the factory returned by this method has been optimized to create objects that minimize the use of memory, thus allowing to keep more objects / records in memory.

Returns:

a singleton ValueFactory

getDatatypeFactory

public static DatatypeFactory getDatatypeFactory()

Returns a DatatypeFactory for creating XMLGregorianCalendar instances and instances of other XML schema structured types.

Returns:

a singleton DatatypeFactory

getTotalComparator

public static Comparator<Object> getTotalComparator()

Returns a comparator imposing a total order over objects of the data model (Values, Statements, Records). Objects are organized in groups: booleans, strings, numbers (longs, ints, ...), calendar dates, URIs, BNodes and records. Ordering is done first based on the group. Then, among a group the ordering is the natural one defined for its elements, where applicable (booleans, strings, numbers, dates), otherwise the following extensions are adopted: (i) statements are sorted by context first, followed by subject, predicate and object; (ii) identifiers are sorted based on their string representation. Note that comparison of dates follows the XML Schema specification with the only exception that incomparable dates according to this specification (due to unknown timezone) are considered equal.

Returns:

a singleton comparator imposing a total order over objects of the data model

getPartialComparator

public static Comparator<Object> getPartialComparator()

Returns a comparator imposing a partial order over objects of the data model (Value s, Statements, Records). This comparator behaves like the one of getTotalComparator() but in case objects belong to different groups (e.g., an integer and a string) an exception is thrown rather than applying group sorting, thus resulting in a more strict comparison that may be useful, e.g., for checking conditions.

Returns:

a singleton comparator imposing a partial order over objects of the data model

getNamespaceMap

public static Map<String,String> getNamespaceMap()

Returns a map of common prefix-to-namespace mappings, taken from a prefix.cc dump. The returned map provides multiple prefixes for some namespace; it also support fast reverse prefix lookup via namespaceToPrefix(String, Map).

Returns:

a singleton map of common prefix-to-namespace mappings

newNamespaceMap

public static Map<String,String> newNamespaceMap()

Creates a new, empty prefix-to-namespace map that supports fast reverse prefix lookup via namespaceToPrefix(String, Map).

Returns:

the created prefix-to-namespace map, empty

newNamespaceMap

public static Map<String,String> newNamespaceMap(Map<String,String> primaryNamespaceMap,
                                                 Map<String,String> secondaryNamespaceMap)

Creates a new prefix-to-namespace map combining the mappings in the supplied maps. Mappings in the primaryNamespaceMap take precedence, while the secondaryNamespaceMap is accessed only if a mapping is not found in the primary map. Modification operations target exclusively the primaryNamespaceMap.

Parameters:

primaryNamespaceMap - the primary prefix-to-namespace map, not null

secondaryNamespaceMap - the secondary prefix-to-namespace map, not null

Returns:

the created, combined prefix-to-namespace map

namespaceToPrefix

@Nullable
public static String namespaceToPrefix(String namespace,
                                                 Map<String,String> namespaceMap)

Performs a reverse lookup of the prefix corresponding to a namespace in a prefix-to-namespace map. This method tries a number of strategy for efficiently performing the reverse lookup, expliting features of the particular prefix-to-namespace map supplied (e.g., whether it is a BiMap from Guava, a namespace map from newNamespaceMap() or the map of common prefix-to-namespace declarations); as a result, calling this method may be significantly faster than manually looping over all the prefix-to-namespace entries.

Parameters:

namespace - the namespace the corresponding prefix should be looked up

namespaceMap - the prefix-to-namespace map containing the searched mapping

Returns:

the prefix corresponding to the namespace, or null if no mapping is defined

isMimeTypeCompressible

public static boolean isMimeTypeCompressible(String mimeType)

Checks whether the specific MIME type can be compressed.

Parameters:

mimeType - the MIME type

Returns:

true if compression can reduce size of data belonging to the specified MIME type, or if there is no knowledge about compressibility of the specified MIME type; false if it is known that compression cannot help (e.g., because the media type is already compressed).

extensionToMimeType

public static String extensionToMimeType(String fileNameOrExtension)

Returns the MIME type for the file extension specified, if known. If the parameter contains a full file name, its extension is extracted and used for the lookup.

Parameters:

fileNameOrExtension - the file extension or file name (from which the extension is extracted)

Returns:

the corresponding MIME type; null if the file extension specified is not contained in the internal database

mimeTypeToExtensions

public static List<String> mimeTypeToExtensions(String mimeType)

Returns the file extensions commonly associated to the specified MIME type. Extensions are reported without a leading '.' (e.g., txt). In case multiple extensions are returned, it is safe to consider the first one as the most common and preferred.

Parameters:

mimeType - the MIME type

Returns:

a list with the extensions mapped to the MIME type, if known; an empty list otherwise

languageCodeToURI

@Nullable
public static org.openrdf.model.URI languageCodeToURI(@Nullable
                                                                String code)
                                                         throws IllegalArgumentException

Returns the language URI for the ISO 639 code (2-letters, 3-letters) specified. The returned URI is in the form http://lexvo.org/id/iso639-3/XYZ.

Parameters:

code - the ISO 639 language code, possibly null

Returns:

the corresponding URI, or null if the input is null

Throws:

IllegalArgumentException - in case the supplied string is not a valid ISO 639 2-letters or 3-letters code

languageURIToCode

@Nullable
public static String languageURIToCode(@Nullable
                                                 org.openrdf.model.URI uri)
                                          throws IllegalArgumentException

Returns the 2-letter ISO 639 code for the language URI supplied. The URI must be in the form http://lexvo.org/id/iso639-3/XYZ.

Parameters:

uri - the language URI, possibly null

Returns:

the corresponding ISO 639 2-letter code, or null if the input URI is null

Throws:

IllegalArgumentException - if the supplied URI is not valid

hash

public static String hash(Object... objects)

Utility method to compute an hash string from a vararg list of objects. The returned string is 16 characters long, starts with A-Za-z and contains only characters A-Za-z0-9.

Parameters:

objects - the objects to compute the hash from

Returns:

the computed hash string

convert

@Nullable
public static <T> T convert(@Nullable
                                      Object object,
                                      Class<T> clazz)
                               throws IllegalArgumentException

General conversion facility. This method attempts to convert a supplied object to an instance of the class specified. If the input is null, null is returned. If conversion is unsupported or fails, an exception is thrown. The following table lists the supported conversions:

From classes (and sub-classes)	To classes (and super-classes)
Boolean, Literal (xsd:boolean)	Boolean, Literal (xsd:boolean), String
String, Literal (plain, xsd:string)	String, Literal (plain, xsd:string), URI (as uri string), BNode (as BNode ID), Integer, Long, Double, Float, Short, Byte, BigDecimal, BigInteger, AtomicInteger, AtomicLong, Boolean, XMLGregorianCalendar, GregorianCalendar, Date (via parsing), Character (length >= 1)
Number, Literal (any numeric xsd: type)	Literal (top-level numeric xsd: type), Integer, Long, Double, Float, Short, Byte, BigDecimal, BigInteger, AtomicInteger, AtomicLong, String
Date, GregorianCalendar, XMLGregorianCalendar, Literal (xsd:dateTime, xsd:date)	Date, GregorianCalendar, XMLGregorianCalendar, Literal (xsd:dateTime), String
URI	URI, Record (ID assigned), String
BNode	BNode, URI (skolemization), String
Statement	Statement, String
Record	Record, URI (ID extracted), String

Type Parameters:

T - the type of result

Parameters:

object - the object to convert, possibly null

clazz - the class to convert to, not null

Returns:

the result of the conversion, or null if object was null

Throws:

IllegalArgumentException - in case conversion fails or is unsupported for the object and class specified

convert

@Nullable
public static <T> T convert(@Nullable
                                      Object object,
                                      Class<T> clazz,
                                      @Nullable
                                      T defaultValue)

General conversion facility, with fall back to default value. This method operates as convert(Object, Class), but in case the input is null or conversion is not supported returns the specified default value.

Type Parameters:

T - the type of result

Parameters:

object - the object to convert, possibly null

clazz - the class to convert to, not null

defaultValue - the default value to fall back to

Returns:

the result of the conversion, or the default value if object was null, conversion failed or is unsupported

normalize

@Nullable
public static Object normalize(@Nullable
                                         Object object)
                                  throws IllegalArgumentException

Normalizes the supplied object to an object of the data model. The method operates as follows:

• if the input is null, null is returned;
• if the input is already an object of the data model (Record, Value, Statement), it is returned unchanged;
• if the input is an iterable or array, its unique element is converted if length is 1; null is returned if length is 0; IllegalArgumentException is thrown otherwise;
• in all the other cases, conversion to Value is performed.

Parameters:

object - the object to normalize, possibly an array or iterable

Returns:

the corresponding object of the data model

Throws:

IllegalArgumentException - in case the supplied object is an array or iterable with more than one element, or if conversion was required but failed or was unsupported

normalize

public static boolean normalize(Object object,
                                Collection<Object> collection)
                         throws IllegalArgumentException

Normalizes the supplied object to zero or more objects of the data model, which are added to the collection specified. The method operates as follows:

• if the input is null, no nodes are produced and false is returned
• if the input is already an object of the data model (Record, Value, Statement), it is stored unchanged in the supplied collection;
• if the input is an iterable or array, its elements are converted recursively (i.e., normalize() is called for each of them, using the same collection supplied);
• in all the other cases, conversion to Value is performed.

Parameters:

object - the object to normalize, possibly an array or iterable

collection - a collection where to add the resulting nodes

Returns:

true, if the collection changed as a result of the call

Throws:

IllegalArgumentException - in case conversion was necessary but failed or was unsupported

validateIRI

public static void validateIRI(@Nullable
                               String string)
                        throws IllegalArgumentException

Check that the supplied string is a legal IRI (as per RFC 3987).

Parameters:

string - the IRI string to check

Throws:

IllegalArgumentException - in case the IRI is illegal

cleanIRI

@Nullable
public static String cleanIRI(@Nullable
                                        String string)
                                 throws IllegalArgumentException

Clean an illegal IRI string, trying to make it legal (as per RFC 3987).

Parameters:

string - the IRI string to clean

Returns:

the cleaned IRI string (possibly the input unchanged) upon success

Throws:

IllegalArgumentException - in case the supplied input cannot be transformed into a legal IRI

cleanURI

public static String cleanURI(String string)
                       throws IllegalArgumentException

Clean a possibly illegal URI string (in a way similar to what a browser does), returning the corresponding cleaned URI object if successfull. A null result is returned for a null input. Cleaning consists in (i) encode Unicode characters above U+0080 as UTF-8 octet sequences and (ii) percent-encode all resulting characters that are illegal as per RFC 3986 (i.e., characters that are not 'reserved' or 'unreserved' according to the RFC). Note that relative URIs are rejected by this method.

Parameters:

string - the input string

Returns:

the resulting cleaned URI

Throws:

IllegalArgumentException - if the supplied string (after being cleaned) is still not valid (e.g., it does not contain a valid URI scheme) or represent a relative URI

parseValue

@Nullable
public static org.openrdf.model.Value parseValue(@Nullable
                                                           String string,
                                                           @Nullable
                                                           Map<String,String> namespaces)
                                                    throws ParseException

Parses an RDF value out of a string. The string can be in the Turtle / N3 / TriG format, i.e., "literal", "literal"^^^datatype, "literal"@lang", <uri>, _:bnode (strings produced by toString(Object, Map, boolean) obey this format).

Parameters:

string - the string to parse, possibly null

namespaces - the optional prefix-to-namespace mappings to use for parsing the string, possibly null

Returns:

the parsed value, or null if a null string was passed as input

Throws:

ParseException - in case parsing fails

toString

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

Returns a string representation of the supplied data model object, optionally using the supplied namespaces and including record properties. Supported objects are Value, Statement, Record instances and instances of scalar types that can be converted to Values (via convert(Object, Class)).

Parameters:

object - the data model object, possibly null

namespaces - the optional prefix-to-namespace mappings to use for generating the string, possibly null

includeProperties - true if record properties should be included in the resulting string, in addition to the record ID

Returns:

the produced string, or null if a null object was passed as input

toString

public static String toString(Object object,
                              @Nullable
                              Map<String,String> namespaces)

Returns a string representation of the supplied data model object, optionally using the supplied namespaces. This method is a shortcut for toString(Object, Map, boolean) when no record properties are desired in output.

Parameters:

object - the data model object, possibly null

namespaces - the optional prefix-to-namespace mappings to use for generating the string, possibly null

Returns:

the produced string, or null if a null object was passed as input