Package org.dspace.content.authority

Interface ChoiceAuthority

All Superinterfaces:
NameAwarePlugin
All Known Subinterfaces:
HierarchicalAuthority
All Known Implementing Classes:
DCInputAuthority, DSpaceControlledVocabulary, EPersonAuthority, SampleAuthority, SHERPARoMEOJournalTitle, SHERPARoMEOPublisher, SolrAuthority, TestAuthority
public interface ChoiceAuthority extends NameAwarePlugin
Plugin interface that supplies an authority control mechanism for one metadata field.
Author:
Larry Stone
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    Choices
    getBestMatch(String text, String locale)
    Get the single "best" match (if any) of a value in the authority to the given user value.
    default Choice
    getChoice(String authKey, String locale)
    Build the preferred choice associated with the authKey.
    default Map<String,String>
    getExtra(String key, String locale)
    Get a map of additional information related to the specified key in the authority.
    String
    getLabel(String key, String locale)
    Get the canonical user-visible "label" (i.e. short descriptive text) for a key in the authority.
    Choices
    getMatches(String text, int start, int limit, String locale)
    Get all values from the authority that match the preferred value.
    default Integer
    getPreloadLevel()
    Hierarchical authority can provide an hint for the UI about how many levels preload to improve the UX.
    default String
    getValue(String key, String locale)
    Get the canonical value to store for a key in the authority.
    default boolean
    isHierarchical()
    Return true for hierarchical authorities
    default boolean
    isScrollable()
    Scrollable authorities allows the scroll of the entries without applying filter/query to the #getMatches(String, String, Collection, int, int, String)
    default boolean
    storeAuthorityInMetadata()
    Provide a recommendation to store the authority in the metadata value if available in the in the provided choice(s).

    Methods inherited from interface org.dspace.core.NameAwarePlugin

    getPluginInstanceName, setPluginInstanceName

  • Method Details

    • getMatches

      Choices getMatches(String text, int start, int limit, String locale)
      Get all values from the authority that match the preferred value. Note that the offering was entered by the user and may contain mixed/incorrect case, whitespace, etc so the plugin should be careful to clean up user data before making comparisons. Value of a "Name" field will be in canonical DSpace person name format, which is "Lastname, Firstname(s)", e.g. "Smith, John Q.". Some authorities with a small set of values may simply return the whole set for any sample value, although it's a good idea to set the defaultSelected index in the Choices instance to the choice, if any, that matches the value.
      Parameters:
      text - user's value to match
      start - choice at which to start, 0 is first.
      limit - maximum number of choices to return, 0 for no limit.
      locale - explicit localization key if available, or null
      Returns:
      a Choices object (never null).

    • getBestMatch

      Choices getBestMatch(String text, String locale)
      Get the single "best" match (if any) of a value in the authority to the given user value. The "confidence" element of Choices is expected to be set to a meaningful value about the circumstances of this match. This call is typically used in non-interactive metadata ingest where there is no interactive agent to choose from among options.
      Parameters:
      text - user's value to match
      locale - explicit localization key if available, or null
      Returns:
      a Choices object (never null) with 1 or 0 values.

    • getLabel

      String getLabel(String key, String locale)
      Get the canonical user-visible "label" (i.e. short descriptive text) for a key in the authority. Can be localized given the implicit or explicit locale specification. This may get called many times while populating a Web page so it should be implemented as efficiently as possible.
      Parameters:
      key - authority key known to this authority.
      locale - explicit localization key if available, or null
      Returns:
      descriptive label - should always return something, never null.

    • getValue

      default String getValue(String key, String locale)
      Get the canonical value to store for a key in the authority. Can be localized given the implicit or explicit locale specification.
      Parameters:
      key - authority key known to this authority.
      locale - explicit localization key if available, or null
      Returns:
      value to store - should always return something, never null.

    • getExtra

      default Map<String,String> getExtra(String key, String locale)
      Get a map of additional information related to the specified key in the authority.
      Parameters:
      key - the key of the entry
      locale - explicit localization key if available, or null
      Returns:
      a map of additional information related to the key

    • isHierarchical

      default boolean isHierarchical()
      Return true for hierarchical authorities
      Returns:
      true if hierarchical, default false

    • isScrollable

      default boolean isScrollable()
      Scrollable authorities allows the scroll of the entries without applying filter/query to the #getMatches(String, String, Collection, int, int, String)
      Returns:
      true if scrollable, default false

    • getPreloadLevel

      default Integer getPreloadLevel()
      Hierarchical authority can provide an hint for the UI about how many levels preload to improve the UX. It provides a valid default for hierarchical authorities
      Returns:
      0 if hierarchical, null otherwise

    • getChoice

      default Choice getChoice(String authKey, String locale)
      Build the preferred choice associated with the authKey. The default implementation delegate the creato to the getLabel(String, String) getValue(String, String) and getExtra(String, String) methods but can be directly overridden for better efficiency or special scenario
      Parameters:
      authKey - authority key known to this authority.
      locale - explicit localization key if available, or null
      Returns:
      the preferred choice for this authKey and locale

    • storeAuthorityInMetadata

      default boolean storeAuthorityInMetadata()
      Provide a recommendation to store the authority in the metadata value if available in the in the provided choice(s). Usually ChoiceAuthority should recommend that so the default is true and it only need to be implemented in the unusual scenario
      Returns:
      true if the authority provided in any choice of this authority should be stored in the metadata value