UCD

java.lang.Object
- ari.ucidy.UCD

All Implemented Interfaces:

java.lang.Iterable<UCDWord>
```
public class UCD
extends java.lang.Object
implements java.lang.Iterable<UCDWord>
```
Representation of a UCD.
This is basically a list of UCD words.

A lot of functions can provide information about different degrees of the validity of this UCD:
Six other functions may gives more information:
- getSuggestion() which proposes a fully valid correction of this UCD (if not already valid ; otherwise the function will return this UCD)
- getErrors() which lists errors preventing this UCD to be fully valid
- getAdvice() which gives some advice about the construction of this UCD (it does not take care about the validity of this UCD)
- containsDeprecated() which tells whether at least one word of this UCD has been deprecated by the IVOA.
- countDeprecated() which counts how many UCD words are deprecated by the IVOA in this UCD.
- getDeprecated() which lists all words deprecated by the IVOA in this UCD.
Version:

1.2 (07/2021)

Author:

Grégory Mantelet (CDS)

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`protected class`	`UCD.AdviceIterator` Iterator over the list of advice.
`protected class`	`UCD.DeprecatedIterator` Iterator over the list of deprecated words.
`protected class`	`UCD.ErrorsIterator` Iterator over the list of all errors.
`protected class`	`UCD.WordsIterator` Iterator over the list of UCD words of this UCD.

Field Summary

Fields
Modifier and Type	Field and Description
`protected java.lang.String[]`	`advice` List of advice concerning the construction of this UCD.
`protected java.lang.Boolean`	`allRecognised` Flag indicating that all words of this UCD are `recognised`.
`protected java.lang.Boolean`	`allRecommended` Flag indicating that all words of this UCD are `recommended`.
`protected java.lang.Boolean`	`allValid` Flag indicating that all words of this UCD are `valid`.
`protected boolean`	`alreadyHasSuggestion` Flag indicating that `suggestion` has been initialized when `getSuggestion()` is called.
`protected UCDWord[]`	`deprecatedWords` List of all `UCDWord.isDeprecated()` deprecated} words in this UCD.
`protected java.lang.String[]`	`errors` List of all errors preventing this UCD to be `fully valid`.
`protected java.lang.Boolean`	`fullyValid` Flag indicating that the whole UCD is `valid`.
`protected static java.lang.String`	`REGEXP_AXIS_FRAME` Regular Expression for any UCD word describing an axis or a reference frame.
`protected static java.lang.String`	`REGEXP_EM` Regular Expression for any UCD word describing a part of the electromagnetic spectrum.
`protected java.lang.String`	`strRepresentation` String serialization of this UCD.
`protected UCD`	`suggestion` Suggestion of a `fully valid` UCD.
`protected UCDWord[]`	`words` UCD words composing this UCD.

Constructor Summary

Constructors
Constructor and Description

UCD(java.util.Collection<UCDWord> words)
Create a UCD with the given words.

UCD(UCDWord[] words)
Create a UCD with the given words.

Constructors
Constructor and Description
`UCD(java.util.Collection<UCDWord> words)` Create a UCD with the given words.
`UCD(UCDWord[] words)` Create a UCD with the given words.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`append(java.lang.StringBuffer buf, java.lang.String word)` Append the given UCD word at the end of the given `StringBuffer`.
`protected void`	`checkAllWords()` Check whether all words are valid, recognised and recommended.
`protected void`	`checkFullValidity()` Check whether this `UCD` is `fully valid`.
`protected java.lang.String`	`concat(java.util.Collection<UCDWord> set)` Concatenate each part of the given collection using `append(StringBuffer, String)`.
`boolean`	`containsDeprecated()` Tell whether at least one word composing this UCD is `UCDWord.isDeprecated()` deprecated}.
`int`	`countDeprecated()` Tell how many words composing this UCD are `UCDWord.isDeprecated()` deprecated}.
`protected void`	`createSuggestion()` Try to create a `fully valid` UCD from this one if it is not already.
`boolean`	`equals(java.lang.Object obj)`
`java.util.Iterator<java.lang.String>`	`getAdvice()` Get advice about UCD words which is possible to add in order to be more precise.
`java.util.Iterator<UCDWord>`	`getDeprecated()` Get all UCD words composing this UCD that are considered as `deprecated`.
`java.util.Iterator<java.lang.String>`	`getErrors()` Get all detected errors preventing this UCD to be fully valid.
`UCD`	`getSuggestion()` Get a suggestion of a `fully valid` UCD created from this one if it is not already `fully valid`.
`UCDWord`	`getWord(int indWord)` Get the specified UCD words of this UCD.
`int`	`hashCode()`
`boolean`	`isAllRecognised()` Tell whether all words composing this UCD are `recognised`.
`boolean`	`isAllRecommended()` Tell whether all words composing this UCD are `recommended`.
`boolean`	`isAllValid()` Tell whether all words composing this UCD are `valid`.
`boolean`	`isFullyValid()` Tell whether all words composing this UCD are `recognised` AND that their order inside the UCD is correct according to their syntax code.
`java.util.Iterator<UCDWord>`	`iterator()` Let iterate over the list of all UCD words composing this UCD.
`protected void`	`listAdvice()` Create a list of some advice.
`protected void`	`listDeprecated()` Create a list of all `deprecated` words found inside this UCD.
`protected void`	`listErrors()` Create a list of all errors.
`protected boolean`	`matches(int indexWord, java.lang.String pattern)` Tell whether the specified UCD word exists and matches the given regular expression.
`protected java.util.LinkedHashSet<UCDWord>`	`searchByPattern(java.lang.String pattern)` Search all UCD words composing this UCD which match the given regular expression.
`int`	`size()` Get the total number of UCD words composing this UCD.
`java.lang.String`	`toString()`

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

Methods inherited from interface java.lang.Iterable
forEach, spliterator

- Field Detail
  - advice
```
protected java.lang.String[] advice
```
    List of advice concerning the construction of this UCD.
    This list is set ONLY when listAdvice() is called or when getAdvice() is called for the first time.
  - allRecognised
```
protected java.lang.Boolean allRecognised
```
    Flag indicating that all words of this UCD are recognised.
    Note that a null word will be considered as not recognised.
    
    This flag is set ONLY when checkAllWords() is called or when isAllValid(), isAllRecognised() or isAllRecommended() is called for the first time.
  - allRecommended
```
protected java.lang.Boolean allRecommended
```
    Flag indicating that all words of this UCD are recommended.
    Note that a null word will be considered as not recommended.
    
    This flag is set ONLY when checkAllWords() is called or when isAllValid(), isAllRecognised() or isAllRecommended() is called for the first time.
  - allValid
```
protected java.lang.Boolean allValid
```
    Flag indicating that all words of this UCD are valid.
    Note that a null word will be considered as not valid.
    
    This flag is set ONLY when checkAllWords() is called or when isAllValid(), isAllRecognised() or isAllRecommended() is called for the first time.
  - alreadyHasSuggestion
```
protected boolean alreadyHasSuggestion
```
    Flag indicating that suggestion has been initialized when getSuggestion() is called.
  - deprecatedWords
```
protected UCDWord[] deprecatedWords
```
    List of all UCDWord.isDeprecated() deprecated} words in this UCD.
    This list is set ONLY when listDeprecated(), getDeprecated()}, countDeprecated() or containsDeprecated() is called for the first time.
    
    Since:
    
    1.2
  - errors
```
protected java.lang.String[] errors
```
    List of all errors preventing this UCD to be fully valid.
    This list is set ONLY when listErrors() is called or when getErrors() is called for the first time.
  - fullyValid
```
protected java.lang.Boolean fullyValid
```
    Flag indicating that the whole UCD is valid.
    This flag is set ONLY when checkFullValidity() is called or when isFullyValid() is called for the first time.
  - REGEXP_AXIS_FRAME
```
protected static java.lang.String REGEXP_AXIS_FRAME
```
    Regular Expression for any UCD word describing an axis or a reference frame.
  - REGEXP_EM
```
protected static java.lang.String REGEXP_EM
```
    Regular Expression for any UCD word describing a part of the electromagnetic spectrum.
  - strRepresentation
```
protected java.lang.String strRepresentation
```
    String serialization of this UCD.
    This field is set ONLY when toString() is called for the first time.
  - suggestion
```
protected UCD suggestion
```
    Suggestion of a fully valid UCD. This is a suggestion of correction of this UCD when it is not already fully valid. Of course, if it already, suggestion will be set to this.
    This field is set ONLY when createSuggestion() is called or when getSuggestion() is called for the first time.
  - words
```
protected final UCDWord[] words
```
    UCD words composing this UCD.
    This array may contain null items.
- Constructor Detail
  - UCD
```
public UCD(java.util.Collection<UCDWord> words)
    throws java.lang.NullPointerException
```
    Create a UCD with the given words.
    
    Parameters:
    
    words - List of words composing this UCD.
    
    Throws:
    
    java.lang.NullPointerException - If the given collection is null.
  - UCD
```
public UCD(UCDWord[] words)
    throws java.lang.NullPointerException
```
    Create a UCD with the given words.
    
    Parameters:
    
    words - List of words composing this UCD.
    
    Throws:
    
    java.lang.NullPointerException - If the given array is null.
- Method Detail
  - append
```
protected final void append(java.lang.StringBuffer buf,
                            java.lang.String word)
```
    Append the given UCD word at the end of the given StringBuffer. The word is added between double quotes and may be prefixed by a comma if not the first word of the StringBuffer.
    Note: If either the buffer or the word is null (or also empty string ONLY in the case of the word) this function does nothing.
    
    Parameters:
    
    buf - The StringBuffer to update.
    
    word - The word to append.
  - checkAllWords
```
protected void checkAllWords()
```
    Check whether all words are valid, recognised and recommended.
    This function updates the flags allValid, allRecognised and allRecommended of this UCD.
    
    Note: If a null word is detected, all flags are automatically set to false.
  - checkFullValidity
```
protected void checkFullValidity()
```
    Check whether this UCD is fully valid.
    This function updates the flag fullyValid of this UCD.
  - concat
```
protected java.lang.String concat(java.util.Collection<UCDWord> set)
```
    Concatenate each part of the given collection using append(StringBuffer, String).
    
    Parameters:
    
    set - The collection of UCDWord to concatenate inside a String.
    
    Returns:
    
    The string serialization of the given collection.
  - containsDeprecated
```
public final boolean containsDeprecated()
```
    Tell whether at least one word composing this UCD is UCDWord.isDeprecated() deprecated}.
    
    Returns:
    
    true if at least one word is UCDWord.isDeprecated() deprecated}, false if not a single word is UCDWord.isDeprecated() deprecated}.
    
    Since:
    
    1.2
  - countDeprecated
```
public final int countDeprecated()
```
    Tell how many words composing this UCD are UCDWord.isDeprecated() deprecated}.
    
    Returns:
    
    The number of UCDWord.isDeprecated() deprecated} words.
    
    Since:
    
    1.2
  - createSuggestion
```
protected void createSuggestion()
```
    Try to create a fully valid UCD from this one if it is not already.
    The following operations may be performed to fix the UCD:
    - In order to make all words recognised: remove all null or empty strings words, and then, remove all leading and trailing spaces and replace all internal space characters by a dot (.).
    - In order to fix the words order to match the individual syntax codes: move the first found PRIMARY word in first position and remove all other PRIMARY words.
    This function will return immediately null in the following cases:
    - when a UCDWord has no syntaxCode
    - if after the fixing operations on a UCD word, it is still not recognised
    - if after removing all null or empty string words, the list of remaining words is empty
  - equals
```
public boolean equals(java.lang.Object obj)
```
    Overrides:
    
    equals in class java.lang.Object
  - getAdvice
```
public final java.util.Iterator<java.lang.String> getAdvice()
```
    Get advice about UCD words which is possible to add in order to be more precise.
    Advice is generally about UCD words of type photometric quantity, colour and vector.
    
    This UCD does not need to be valid so that this function provides advice.
    
    Returns:
    
    The proposed advice.
  - getDeprecated
```
public final java.util.Iterator<UCDWord> getDeprecated()
```
    Get all UCD words composing this UCD that are considered as deprecated.
    
    Returns:
    
    All the deprecated words.
    
    Since:
    
    1.2
  - getErrors
```
public final java.util.Iterator<java.lang.String> getErrors()
```
    Get all detected errors preventing this UCD to be fully valid.
    
    Returns:
    
    All detected errors.
  - getSuggestion
```
public final UCD getSuggestion()
```
    Get a suggestion of a fully valid UCD created from this one if it is not already fully valid.
    
    Returns:
    
    This UCD if it is already fully valid, or a new UCD proposing a fully valid alternative to this UCD, or null if no suggestion of correction can be found.
  - getWord
```
public final UCDWord getWord(int indWord)
                      throws java.lang.ArrayIndexOutOfBoundsException
```
    Get the specified UCD words of this UCD.
    
    Parameters:
    
    indWord - Index of the UCD word to get.
    
    Returns:
    
    The corresponding UCD word.
    
    Throws:
    
    java.lang.ArrayIndexOutOfBoundsException - If the given index if negative, or equal or greater than the size of this UCD.
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class java.lang.Object
  - isAllRecognised
```
public final boolean isAllRecognised()
```
    Tell whether all words composing this UCD are recognised.
    
    Returns:
    
    true if all words are recognised, false if at least one word is not recognised.
  - isAllRecommended
```
public final boolean isAllRecommended()
```
    Tell whether all words composing this UCD are recommended.
    
    Returns:
    
    true if all words are recommended, false if at least one word is not recommended.
  - isAllValid
```
public final boolean isAllValid()
```
    Tell whether all words composing this UCD are valid.
    
    Returns:
    
    true if all words are valid, false if at least one word is not valid.
  - isFullyValid
```
public final boolean isFullyValid()
```
    Tell whether all words composing this UCD are recognised AND that their order inside the UCD is correct according to their syntax code.
    Only PRIMARY ('P') and SECONDARY ('S') are considered here.
    
    Returns:
    
    true if the whole UCD is syntactically correct, false otherwise.
  - iterator
```
public final java.util.Iterator<UCDWord> iterator()
```
    Let iterate over the list of all UCD words composing this UCD.
    
    Specified by:
    
    iterator in interface java.lang.Iterable<UCDWord>
    
    See Also:
    
    Iterable.iterator()
  - listAdvice
```
protected void listAdvice()
```
    Create a list of some advice.
    Advice is given in the following cases:
    - one or more UCD words are duplicated
    - a recommended word has an explicit ivoa namespace prefix
    - a recognised custom word with a namespace is used (it is preferred to use recommended UCD words representing the same quantity instead)
    - a photometric quantity is not followed directly by a part of the EM spectrum (see REGEXP_EM)
    - a color is not followed directly by 2 successive parts of the EM spectrum (see REGEXP_EM)
    - a vector is not followed directly by an axis or a reference frame
  - listDeprecated
```
protected void listDeprecated()
```
    Create a list of all deprecated words found inside this UCD.
    Duplicated deprecated words are listed only once.
    
    Since:
    
    1.2
  - listErrors
```
protected void listErrors()
```
    Create a list of all errors.
    Errors are grouped by category:
    - null or empty words
    - Not valid words
    - Words with no syntax code (that's to say: not recognised words)
    - PRIMARY words NOT at the first position or more than one is detected
    - SECONDARY word at the first position
  - matches
```
protected boolean matches(int indexWord,
                          java.lang.String pattern)
```
    Tell whether the specified UCD word exists and matches the given regular expression.
    Warning: The UCD word's namespace is ignored ; the regular expression must apply only on the word.
    
    Parameters:
    
    indexWord - The index of the UCD word to test.
    
    pattern - A regular expression.
    
    Returns:
    
    true if the specified word exists and matches the given regular expression, false otherwise.
  - searchByPattern
```
protected java.util.LinkedHashSet<UCDWord> searchByPattern(java.lang.String pattern)
```
    Search all UCD words composing this UCD which match the given regular expression.
    Warning: The UCD word's namespace is ignored ; the regular expression must apply only on the word.
    
    Parameters:
    
    pattern - A regular expression.
    
    Returns:
    
    A set containing (by order of apparition) all UCD words matching the given regular expression.
  - size
```
public final int size()
```
    Get the total number of UCD words composing this UCD.
    
    Returns:
    
    Number of words inside this UCD.
  - toString
```
public final java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object

Class UCD

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Iterable

Field Detail

advice

allRecognised

allRecommended

allValid

alreadyHasSuggestion

deprecatedWords

errors

fullyValid

REGEXP_AXIS_FRAME

REGEXP_EM

strRepresentation

suggestion

words

Constructor Detail

UCD

UCD

Method Detail

append

checkAllWords

checkFullValidity

concat

containsDeprecated

countDeprecated

createSuggestion

equals

getAdvice

getDeprecated

getErrors

getSuggestion

getWord

hashCode

isAllRecognised

isAllRecommended

isAllValid

isFullyValid

iterator

listAdvice

listDeprecated

listErrors

matches

searchByPattern

size

toString