Package uk.ac.starlink.vo

## Class RegistryProtocol

- java.lang.Object
- - uk.ac.starlink.vo.RegistryProtocol

-     public abstract class RegistryProtocol
      extends java.lang.Object

  Defines the details of a registry access protocol.
  Since:
    9 Apr 2014
  Author:
    Mark Taylor

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static RegistryProtocol[]` | `PROTOCOLS` | Known protocols.
    `static RegistryProtocol` | `REGTAP` | Protocol instance for Relational Registry 1.0.
    `static RegistryProtocol` | `RI1` | Protocol instance for Registry Interface 1.0.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `RegistryProtocol​(java.lang.String shortName, java.lang.String fullName, java.lang.String[] dfltUrls)` | Constructor.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `abstract RegistryQuery` | `createIdListQuery​(java.lang.String[] ivoids, Capability capability, java.net.URL regUrl)` | Constructs a registry query that gets results for a list of given IVO ID strings, optionally restricted by a given capability.
    `abstract RegistryQuery` | `createKeywordQuery​(java.lang.String[] keywords, ResourceField[] rfs, boolean isOr, Capability capability, java.net.URL regUrl)` | Constructs a registry query that gets results for resources with a match for one or all of a given set of keywords found in a selection of resource fields.
    `abstract java.lang.String[]` | `discoverRegistryUrls​(java.lang.String regUrl0)` | Searches a given registry to discover new endpoint URLs serving this registry protocol.
    `java.lang.String[]` | `getDefaultRegistryUrls()` | Returns default endpoint URLs for this protocol.
    `java.lang.String` | `getFullName()` | Returns the full name for this protocol.
    `java.lang.String` | `getShortName()` | Returns a short name for this protocol.
    `abstract boolean` | `hasCapability​(Capability stdCap, RegCapabilityInterface resCap)` | Indicates whether a given RegCapabilityInterface object is an instance of a given capability.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### RI1

          public static final RegistryProtocol RI1

      Protocol instance for Registry Interface 1.0.

    - #### REGTAP

          public static final RegistryProtocol REGTAP

      Protocol instance for Relational Registry 1.0.

    - #### PROTOCOLS

          public static final RegistryProtocol[] PROTOCOLS

      Known protocols.

  - ### Constructor Detail

    - #### RegistryProtocol

          protected RegistryProtocol​(java.lang.String shortName,
                                     java.lang.String fullName,
                                     java.lang.String[] dfltUrls)

      Constructor.
      Parameters:
        `shortName` - short name
        `fullName` - full name
        `dfltUrls` - strings giving some default registry endpoints for this access protocol

  - ### Method Detail

    - #### getShortName

          public java.lang.String getShortName()

      Returns a short name for this protocol.
      Returns:
        short name

    - #### getFullName

          public java.lang.String getFullName()

      Returns the full name for this protocol.
      Returns:
        full name

    - #### getDefaultRegistryUrls

          public java.lang.String[] getDefaultRegistryUrls()

      Returns default endpoint URLs for this protocol.
      Returns:
        endpoint URL strings

    - #### discoverRegistryUrls

          public abstract java.lang.String[] discoverRegistryUrls​(java.lang.String regUrl0)
                                                           throws java.io.IOException

      Searches a given registry to discover new endpoint URLs serving this registry protocol.
      Parameters:
        `regUrl0` - bootstrap registry endpoint URL
      Returns:
        registry endpoint URLs discovered from the registry
      Throws:
        `java.io.IOException`

    - #### createIdListQuery

          public abstract RegistryQuery createIdListQuery​(java.lang.String[] ivoids,
                                                          Capability capability,
                                                          java.net.URL regUrl)

      Constructs a registry query that gets results for a list of given IVO ID strings, optionally restricted by a given capability. The resulting query supplies results for each resource which is all of: (a) in the registry, (b) in the `ivoids` list, and (c) has the given capability If `capability` is null, then restriction (c) does not apply. If the input list of IDs is null or empty, the return value will be null.
      Parameters:
        `ivoids` - ID values for the required resources
        `capability` - service capability type, or null
        `regUrl` - endpoint URL for a registry service implementing this protocol
      Returns:
        registry query, or null for empty ID list

    - #### createKeywordQuery

          public abstract RegistryQuery createKeywordQuery​(java.lang.String[] keywords,
                                                           ResourceField[] rfs,
                                                           boolean isOr,
                                                           Capability capability,
                                                           java.net.URL regUrl)

      Constructs a registry query that gets results for resources with a match for one or all of a given set of keywords found in a selection of resource fields.
      Parameters:
        `keywords` - single-word keywords to match independently
        `rfs` - resource fields against which keywords are to match
        `isOr` - if false all keywords must match, if true at least one keyword must match
        `capability` - if non-null, restricts the resources to those with that capability
        `regUrl` - endpoint URL for a registry service implementing this protocol
      Returns:
        registry query

    - #### hasCapability

          public abstract boolean hasCapability​(Capability stdCap,
                                                RegCapabilityInterface resCap)

      Indicates whether a given RegCapabilityInterface object is an instance of a given capability. This is typically used to weed out RegCapabilityInterface objects returned from a query that might have returned some items different than those queried.

      Really, the implementation of this ought not to be a function of the registry protocol in use. However, it's probably the case that the different registry implementations have different quirks in this respect, so take the opportunity to parameterise it by registry protocol in case that's required.

      Parameters:
        `stdCap` - standard capability definition
        `resCap` - capability interface object representing part of a registry resource
      Returns:
        true iff `resCap` represents a capability of the type `stdCap`