org.apache.stanbol.entityhub.servicesapi.model
Interface Representation

public interface Representation

This interface is used by the Entityhub to define representations. It is used for any kind of CRUD operations on the Yard (the storage of the Entityhub).
The goal if this interface is to allow implementation based on different storage solutions such as CMS, full text indices, triple stores, noSQL data stores ...
TODO: handling the differences between "NaturalLanguageText", "References" and "normal" values feels to complex! Need to reevaluate if this differentiation is needed or can be done in a more easy way! TODO: add an API that allows to attach Content! TODO: Do we need subNodes or are "references" enough. TODO: Check to use also Wrappers for fields and values (in analogy to Reference and Text. PRO: clearer API CON: more Objects to be garbage collected.

Author:

Rupert Westenthaler

Method Summary

void	add(String field, Object value) Adds the object as value to the field.
void	addNaturalText(String field, String text, String... languages) Adds a natural language text as value for one or more languages
void	addReference(String field, String reference) Adds an reference to the field.
Iterator<Object>	get(String field) Getter for all values for the requested field
<T> Iterator<T>	get(String field, Class<T> type) Getter for all values of a field
Iterator<Text>	get(String field, String... language) Getter for all natural language text values of a field
Iterator<String>	getFieldNames() Getter for all the present fields
Object	getFirst(String field) Getter for the (first) value for a field
<T> T	getFirst(String field, Class<T> type) Getter for a single Value for a field
Text	getFirst(String field, String... language) Getter for the first natural language text value of a specific language
Reference	getFirstReference(String field) Getter for the first reference value for a field
String	getId() Getter for the identifier.
Iterator<Reference>	getReferences(String field) Getter for all reference values of a field
Iterator<Text>	getText(String field) Getter for all natural language text values of a field
void	remove(String field, Object value) Removes the parsed value form the field.
void	removeAll(String field) Removes all values of the field
void	removeAllNaturalText(String field, String... languages) Removes all natural language texts for the given languages or all natural language labels of no language or an empty array is parsed as language.
void	removeNaturalText(String field, String text, String... languages) Removes a natural language text in given languages form a field
void	removeReference(String field, String reference) Removes to parsed reference as value for the given field.
void	set(String field, Object value) Sets the value of the field to the parsed object.
void	setNaturalText(String field, String text, String... language) Setter for the natural language text value of a field in the given languages.
void	setReference(String field, String reference) Setter for the reference of a field.

Method Detail

getId

String getId()

Getter for the identifier.

Returns:

the identifier

getFirst

<T> T getFirst(String field,
               Class<T> type)
           throws UnsupportedTypeException,
                  IllegalArgumentException

Getter for a single Value for a field

Type Parameters:

T - the generic type the returned value

Parameters:

field - the field

type - the type of the values

Returns:

the (first) value of that field

Throws:

IllegalArgumentException - if the type is not supported

IllegalArgumentException - if null or an empty string is parsed as field

UnsupportedTypeException

get

<T> Iterator<T> get(String field,
                    Class<T> type)
                throws UnsupportedTypeException,
                       IllegalArgumentException

Getter for all values of a field

Type Parameters:

T - the generic type of the returned values

Parameters:

field - the field

type - the type

Returns:

the values of the field

Throws:

UnsupportedTypeException - if the parsed type is not supported

IllegalArgumentException - if null or an empty string is parsed as field

getFirst

Object getFirst(String field)
                throws IllegalArgumentException

Getter for the (first) value for a field

Parameters:

field - the field

Returns:

the first value of a field

Throws:

IllegalArgumentException - if null or an empty string is parsed as field

getFirstReference

Reference getFirstReference(String field)
                            throws IllegalArgumentException

Getter for the first reference value for a field

Parameters:

field - the field

Returns:

the reference or null of the field has no reference as value

Throws:

IllegalArgumentException - if null or an empty string is parsed as field

getFirst

Text getFirst(String field,
              String... language)
              throws IllegalArgumentException

Getter for the first natural language text value of a specific language

Parameters:

field - the field

language - the language(s) of the natural language text value (If null is parsed as language, than also labels without language tag are included in the Result)

Returns:

the first natural language text found for the parsed field

Throws:

IllegalArgumentException - if null or an empty string is parsed as field

get

Iterator<Object> get(String field)
                     throws IllegalArgumentException

Getter for all values for the requested field

Parameters:

field - the field

Returns:

the values of the field

Throws:

IllegalArgumentException - if null or an empty string is parsed as field

getText

Iterator<Text> getText(String field)
                       throws IllegalArgumentException

Getter for all natural language text values of a field

Parameters:

field - the field

Returns:

the natural text values

Throws:

IllegalArgumentException - if null or an empty string is parsed as field

get

Iterator<Text> get(String field,
                   String... language)
                   throws IllegalArgumentException

Getter for all natural language text values of a field

Parameters:

field - the field

language - the language(s) of the natural language text value (If null is parsed as language, than also labels without language tag are included in the Result)

Returns:

iterator over all natural language text values in the requested language.

Throws:

IllegalArgumentException - if null or an empty string is parsed as field

getReferences

Iterator<Reference> getReferences(String field)
                                  throws IllegalArgumentException

Getter for all reference values of a field

Parameters:

field - the field

Returns:

Iterator over all reference values of a field

Throws:

IllegalArgumentException - if null or an empty string is parsed as field

add

void add(String field,
         Object value)
         throws IllegalArgumentException

Adds the object as value to the field.

The type of the value is inferred based on the type of the Object.
Supported Types are:

• Reference
• URL, URI: Reference instances are created for such values
• Boolean, Integer, Long, Double and Float as primitive data types
• Date
• Text
• String[]{text,language}: text and language (further entries are ignored)
• String: mapped to Text with the language=null
• Collections, Enumerations and Iterators are can be used to parse multiple values
• For unsupported types it MUSST be assured the the toString() value of the stored Object is equals to the toString() value of the parsed object.

Parameters:

field - the field

value - the value to add

Throws:

NullPointerException

IllegalArgumentException - if null is parsed as field or value and/or if an empty string is parsed as field

addReference

void addReference(String field,
                  String reference)
                  throws IllegalArgumentException

Adds an reference to the field.

Parameters:

field - the field

reference - the string representation of the reference. Note that the value will be interpreted as a "reference" so there might apply some rules about the format of the string. Regardless of the implementation any valid URI and URL need to be accepted as a valid reference value

Throws:

NullPointerException

IllegalArgumentException - if null or an empty string is parsed as field or reference

addNaturalText

void addNaturalText(String field,
                    String text,
                    String... languages)
                    throws IllegalArgumentException

Adds a natural language text as value for one or more languages

Parameters:

field - the field to add the text as value

text - the natural language text

language - the text is set for all the parsed languages. Parse null to set the text also without any language information.

Throws:

NullPointerException

IllegalArgumentException - if null or an empty string is parsed as field; if null is parsed as text. NOTE that null is supported for languages.

set

void set(String field,
         Object value)
         throws IllegalArgumentException

Sets the value of the field to the parsed object. If the parsed value is null than this method removes all values for the given field
This Method supports collections as well as value conversions for some types. Please see the documentation of add(String, Object) for details.

Parameters:

field - the field

value - the new value for the field

Throws:

NullPointerException

IllegalArgumentException - if null or an empty string is parsed as field

setReference

void setReference(String field,
                  String reference)
                  throws IllegalArgumentException

Setter for the reference of a field. If the parsed value is null than this method removes all values for the given field.

Parameters:

field - the field

reference - the string representation of the reference. Note that the value will be interpreted as a "reference" so there might apply some rules about the format of the string. Regardless of the implementation any valid URI and URL need to be accepted as a valid reference value

Throws:

IllegalArgumentException - if nullor an emtpy string is parsed as field

setNaturalText

void setNaturalText(String field,
                    String text,
                    String... language)
                    throws IllegalArgumentException

Setter for the natural language text value of a field in the given languages. If null is parsed as text, all present values for the parsed languages are removed (values of other languages are not removed)

Parameters:

field - the field

text - the natural language text

language - the languages of the parsed text. Parse null to set the text also without any language information.

Throws:

IllegalArgumentException - if nullor an emtpy string is parsed as field

remove

void remove(String field,
            Object value)
            throws IllegalArgumentException

Removes the parsed value form the field. If null is parsed as value than the call is ignored.

This methods follows the same conventions as add(String, Object) (e.g. parsing a Collection will cause all values within this collection to be removed). See the documentation of add(String, Object) for details.

Parameters:

field - the field

value - the value to remove

Throws:

IllegalArgumentException - if nullor an emtpy string is parsed as field

removeReference

void removeReference(String field,
                     String reference)
                     throws NullPointerException,
                            IllegalArgumentException

Removes to parsed reference as value for the given field. If null is parsed as reference, that the call is ignored.

Parameters:

field - the field

reference - the string representation of the reference. Note that the value will be interpreted as a "reference" so there might apply some rules about the format of the string. Regardless of the implementation any valid URI and URL need to be accepted as a valid reference value

Throws:

NullPointerException - if null is parsed as field

IllegalArgumentException - if an empty string is parsed as field

removeNaturalText

void removeNaturalText(String field,
                       String text,
                       String... languages)
                       throws IllegalArgumentException

Removes a natural language text in given languages form a field

Parameters:

field - the field

text - the natural language text

language - the language(s) of the natural language text (If null is parsed as language, than also labels without language tag might be removed)

Throws:

IllegalArgumentException - if nullor an emtpy string is parsed as field

removeAll

void removeAll(String field)
               throws IllegalArgumentException

Removes all values of the field

Parameters:

field - the field

Throws:

IllegalArgumentException - if nullor an emtpy string is parsed as field

removeAllNaturalText

void removeAllNaturalText(String field,
                          String... languages)
                          throws IllegalArgumentException

Removes all natural language texts for the given languages or all natural language labels of no language or an empty array is parsed as language. To remove values with no language, parse null as entry of the languages array.

Parameters:

field - the field.

languages - the language(s) of the natural language text. If null or an empty array is parsed, than all natural language label are removed. To remove only labels with no language, null needs to be parsed as entry of this array.

Throws:

IllegalArgumentException - if nullor an emtpy string is parsed as field

getFieldNames

Iterator<String> getFieldNames()

Getter for all the present fields

Returns:

the fields