ari.ucidy

Class UCDWordList

java.lang.Object

ari.ucidy.UCDWordList

All Implemented Interfaces:

java.lang.Iterable<UCDWord>

Direct Known Subclasses:

DeprecatedUCDWordList

public class UCDWordList
extends java.lang.Object
implements java.lang.Iterable<UCDWord>

Object listing and ordering alphabetically a set of UCD words.

Searching UCD words

This object behaves like a dictionary. It is possible to search UCD words in different ways:

• For a specific UCD word: get(String) (namespaces ignored), get(String, boolean)
• For all UCD words starting with a given string: startingWith(String)
• For a UCD word with some typographical errors: getClosest(String)
• For UCD whose the description (and also the word's atoms) matches some keywords: search(String)

Import from a file

A list of UCD word definitions can be imported from a PSV (Pipe-Separated-Value) file using addAll(File), addAll(File, boolean), addAll(InputStream, boolean) or addAll(Reader, boolean). The first function will import all identified UCD words as NOT recommended. If you want to change this behaviour, use addAll(File, boolean) instead.

Version

A version can be associated with this UCD words list. This piece of information has to be provided at initialization with UCDWordList(String). Then it can be get at anytime thanks to getVersion().

Version:

1.2 (11/2021)

Author:

Grégory Mantelet (CDS)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	UCDWordList.UCDWordComparator Class used to sort the UCD words in this UCDWordList.

Field Summary

Fields

Modifier and Type	Field and Description
protected static java.util.logging.Logger	LOGGER Logger used to report errors during the initialization of the default UCDWordList.
protected java.util.TreeSet<UCDWord>	words List of all known UCD words.

Constructor Summary

Constructors

Constructor and Description
UCDWordList() Create an empty list of UCD words.
UCDWordList(java.lang.String version) Create an empty list of UCD words.

Method Summary

Modifier and Type	Method and Description
boolean	add(UCDWord newWord) Add the given UCD word.
int	addAll(java.util.Collection<UCDWord> newWords) Add all the UCD words listed in the given collection.
int	addAll(java.io.File psvFile) Add all UCD words declared using the PSV (Pipe-Separated-Value) format inside the specified file.
int	addAll(java.io.File psvFile, boolean recommended) Add all UCD words declared using the PSV (Pipe-Separated-Value) format inside the specified file.
int	addAll(java.io.InputStream stream, boolean recommended) Add all UCD words declared using the PSV (Pipe-Separated-Value) format inside the specified input stream.
int	addAll(java.io.Reader reader, boolean recommended) Add all UCD words declared using the PSV (Pipe-Separated-Value) format inside the specified reader.
int	addAll(UCDWord[] newWords) Add all the UCD words listed in the given array.
void	clear() Remove ALL UCD words listed in this object.
boolean	contains(java.lang.String ucdWord) Tell whether the given UCD word is part of this list.
UCDWord	get(java.lang.String ucdWord) Search for an exact match with the given UCD word but while ignoring their namespace.
UCDWord	get(java.lang.String ucdWord, boolean checkNamespace) Search for an exact match with the given supposed UCD word.
UCDWord[]	getClosest(java.lang.String wrongWord) Search for a UCD word the closest as possible from the given one.
java.lang.String	getVersion() Get the version of this UCD words list.
java.util.Iterator<UCDWord>	iterator() Let iterate (by alphabetic order) over the whole list of UCD words.
protected static int	lev_min(int a, int b, int c) Compute the minimum value among the three given one.
protected static int	levenshtein(java.lang.String left, java.lang.String right) Compute the Levenshtein distance between the two given strings.
static void	main(java.lang.String[] args)
UCDWord	remove(java.lang.String ucdWord) Remove the UCD word matching the given one.
java.util.Set<UCDWord>	search(java.lang.String keywords) Search for all UCD words whose the description matches the given keywords.
int	size() Total number of UCD words stored in this list.
java.util.SortedSet<UCDWord>	startingWith(java.lang.String startStr) Search for all UCD words starting with the given string.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

LOGGER

protected static final java.util.logging.Logger LOGGER

Logger used to report errors during the initialization of the default UCDWordList.

Since:

1.2

words

protected java.util.TreeSet<UCDWord> words

List of all known UCD words.

Constructor Detail

UCDWordList

public UCDWordList()

Create an empty list of UCD words.

UCDWordList

public UCDWordList(java.lang.String version)

Create an empty list of UCD words.

Parameters:

version - Version of the words list. May be NULL.

Since:

1.2

Method Detail

add

public boolean add(UCDWord newWord)

Add the given UCD word.

Parameters:

newWord - The UCD word to add.

Returns:

true if the given UCD word has been successfully added, false if the given word is null, is not valid, is not recognised, is not recommended and uses the ivoa namespace, or already exists in the list.

addAll

public int addAll(java.util.Collection<UCDWord> newWords)

Add all the UCD words listed in the given collection.

Note: null items are ignored.

Parameters:

newWords - A collection of new UCD words to add.

Returns:

The number of successfully added UCD words, or 0 if the given collection is null.

addAll

public int addAll(java.io.File psvFile)
           throws java.lang.NullPointerException,
                  java.io.IOException

Add all UCD words declared using the PSV (Pipe-Separated-Value) format inside the specified file.

The real parsing is performed by UCDParser.parseWordList(Reader, boolean, UCDWordList). Please take a look to its Javadoc for more details about the expected syntax and the possible errors that can occur.

Note: This function will import all UCD words as NOT recommended. If you want to import them as recommended, use addAll(File, boolean) instead with the second parameter set to true.

Parameters:

psvFile - PSV file to parse.

Returns:

The number of successfully added UCD words extracted from the file.

Throws:

java.lang.NullPointerException - If the given file is null.

java.io.IOException - If an error occurred while reading the specified file.

See Also:

addAll(File, boolean)

addAll

public int addAll(java.io.File psvFile,
                  boolean recommended)
           throws java.lang.NullPointerException,
                  java.io.IOException

Add all UCD words declared using the PSV (Pipe-Separated-Value) format inside the specified file.

The real parsing is performed by UCDParser.parseWordList(Reader, boolean, UCDWordList). Please take a look to its Javadoc for more details about the expected syntax and the possible errors that can occur.

Parameters:

psvFile - PSV file to parse.

recommended - true to flag all imported UCD words as recommended, false otherwise.

Returns:

The number of successfully added UCD words extracted from the file.

Throws:

java.lang.NullPointerException - If the given file is null.

java.io.IOException - If an error occurred while reading the specified file.

See Also:

addAll(Reader, boolean)

addAll

public int addAll(java.io.InputStream stream,
                  boolean recommended)
           throws java.lang.NullPointerException,
                  java.io.IOException

Add all UCD words declared using the PSV (Pipe-Separated-Value) format inside the specified input stream.

The real parsing is performed by UCDParser.parseWordList(Reader, boolean, UCDWordList). Please take a look to its Javadoc for more details about the expected syntax and the possible errors that can occur.

Parameters:

stream - Input stream to parse.

recommended - true to flag all imported UCD words as recommended, false otherwise.

Returns:

The number of successfully added UCD words extracted from the input stream.

Throws:

java.lang.NullPointerException - If the given stream is null.

java.io.IOException - If an error occurred while reading the specified stream.

See Also:

addAll(Reader, boolean)

addAll

public int addAll(java.io.Reader reader,
                  boolean recommended)
           throws java.lang.NullPointerException,
                  java.io.IOException

Add all UCD words declared using the PSV (Pipe-Separated-Value) format inside the specified reader.

The real parsing is performed by UCDParser.parseWordList(Reader, boolean, UCDWordList). Please take a look to its Javadoc for more details about the expected syntax and the possible errors that can occur.

Parameters:

reader - Reader whose the content must be parsed.

recommended - true to flag all imported UCD words as recommended, false otherwise.

Returns:

The number of successfully added UCD words extracted from the input.

Throws:

java.lang.NullPointerException - If the given reader is null.

java.io.IOException - If an error occurred while reading the specified input.

See Also:

UCDParser.parseWordList(Reader, boolean, UCDWordList)

addAll

public int addAll(UCDWord[] newWords)

Add all the UCD words listed in the given array.

Note: null items are ignored.

Parameters:

newWords - An array of new UCD words to add.

Returns:

The number of successfully added UCD words, or 0 if the given array is null.

clear

public void clear()

Remove ALL UCD words listed in this object.

contains

public boolean contains(java.lang.String ucdWord)

Tell whether the given UCD word is part of this list.

Important note: Comparisons are case INsensitive and the namespaces are ignored.

Parameters:

ucdWord - The UCD word to test.

Returns:

true if the given UCD word exists in this list, false otherwise (and particularly if the given word is null).

get

public UCDWord get(java.lang.String ucdWord)

Search for an exact match with the given UCD word but while ignoring their namespace.

Important note: Comparisons are case INsensitive and the namespaces are ignored.

Warning: If this function returns a UCDWord, it may have a different namespace than the one of the given UCD word. To search on the word AND on the namespace you should use get(String, boolean) or apply a final test on the namespace of the returned word.

Parameters:

ucdWord - The UCD word to search.

Returns:

The corresponding UCDWord instance matching the given UCD word, or null if the given word is null, an empty string or can not be found in this list.

See Also:

get(String, boolean)

get

public UCDWord get(java.lang.String ucdWord,
                   boolean checkNamespace)

Search for an exact match with the given supposed UCD word.

Important note: Comparisons are case INsensitive.

Parameters:

ucdWord - The UCD word to search.

checkNamespace - true to ensure the namespace of the match is the same as the one of the given word, false to search only on the word and not check the namespace.

Returns:

The corresponding UCDWord instance matching the given UCD word, or null if the given word is null, an empty string or can not be found in this list.

getClosest

public UCDWord[] getClosest(java.lang.String wrongWord)

Search for a UCD word the closest as possible from the given one.

This function aims to help fixing typo in a given UCD word. It uses the Levenshtein algorithm to determine the UCD word of this list which requires the fewest number of editions (i.e. add, replace and remove a character) to match the given word.

This function is designed to select UCD words with a number of required editions less or equal to half the length of the given word. Consequently, smaller is the given word, smaller are the probabilities to find a closest match in this list. In other words, this function should not be used for small words (e.g. less than 3-4 characters).

Note 1: It is entirely possible that several words have the same distance from the given word. In such case, this function will return all candidates in an array.

Note 2: Search is performed case INsensitive and the namespaces are ignored.

Parameters:

wrongWord - The word to fix.

Returns:

List of all the closest UCDWords from the given UCD word.

getVersion

public final java.lang.String getVersion()

Get the version of this UCD words list.

Returns:

Words list version.

Since:

1.2

iterator

public java.util.Iterator<UCDWord> iterator()

Let iterate (by alphabetic order) over the whole list of UCD words.

Specified by:

iterator in interface java.lang.Iterable<UCDWord>

See Also:

Iterable.iterator()

lev_min

protected static int lev_min(int a,
                             int b,
                             int c)

Compute the minimum value among the three given one.

This function is used only by levenshtein(String, String) ; hence its name.

Parameters:

a - A value.

b - Another value.

c - A last value.

Returns:

The minimum of a, b and c.

levenshtein

protected static int levenshtein(java.lang.String left,
                                 java.lang.String right)
                          throws java.lang.NullPointerException

Compute the Levenshtein distance between the two given strings.

Short definition of the Levenshtein algorithm by Wikipedia:

In information theory and computer science, the Levenshtein distance is a string metric for measuring the difference between two sequences. Informally, the Levenshtein distance between two words is the minimum number of single-character edits (i.e. insertions, deletions or substitutions) required to change one word into the other.

This function has been strongly inspired of the Java code source provided on http://rosettacode.org/wiki/Levenshtein_distance#Java

Parameters:

left - A first string. Must NOT be NULL

right - A second string. Must NOT be NULL

Returns:

The distance between the two given strings. 0 is a perfect equality ; max(left.length, right.length) is a perfect difference.

Throws:

java.lang.NullPointerException - If one of the given string is null.

main

public static void main(java.lang.String[] args)
                 throws java.lang.Throwable

Throws:

java.lang.Throwable

remove

public UCDWord remove(java.lang.String ucdWord)

Remove the UCD word matching the given one.

Important note: Comparisons are case INsensitive and the namespaces are ignored.

Parameters:

ucdWord - The UCD word to remove from this list.

Returns:

The removed UCD word, or null if no UCD word matches.

search

public java.util.Set<UCDWord> search(java.lang.String keywords)

Search for all UCD words whose the description matches the given keywords.

Important note: Comparisons are case insensitive.

Parameters:

keywords - String concatenating (with space characters) some keywords.

Returns:

A set of UCD words whose the description matches the given keywords. This set is ordered by descending score.

size

public int size()

Total number of UCD words stored in this list.

Returns:

Number of stored UCD words.

startingWith

public java.util.SortedSet<UCDWord> startingWith(java.lang.String startStr)

Search for all UCD words starting with the given string.

Important note: Comparisons are case INsensitive and the namespaces are ignored.

Parameters:

startStr - The starting string.

Returns:

A sorted set containing all UCD words starting with the given string, or null if the given string is null, empty or can not be found in this list.