eu.erasmuswithoutpaper.registryclient

Interface RegistryClient

All Superinterfaces:

AutoCloseable

All Known Implementing Classes:

ClientImpl

public interface RegistryClient
extends AutoCloseable

Allows to perform basic queries to EWP Registry Service.

This interface exists in order for developers to be able supply their own alternative implementations (e.g. for testing purposes). Usually you will use ClientImpl as the implementation of this interface. Remember to call close() after you're done with instances of this interface.

Since:

1.0.0

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	RegistryClient.AssertionFailedException Thrown whenever one of the RegistryClient's assert* methods fails its assertion.
static class	RegistryClient.InvalidApiEntryElement Thrown whenever an invalid API-entry Element has been passed to one of the RegistryClient's methods.
static class	RegistryClient.RefreshFailureException Thrown by refresh() when the catalogue refreshing fails for some reason.
static class	RegistryClient.RegistryClientException A common base for all RegistryClient checked exceptions.
static class	RegistryClient.RegistryClientRuntimeException A common base for all RegistryClient runtime exceptions.
static class	RegistryClient.StaleApiEntryElement Thrown whenever a stale API-entry Element has been passed to one of the RegistryClient 's methods.
static class	RegistryClient.UnacceptableStalenessException Thrown by multiple RegistryClient methods when their internal copy of the Registry's catalogue is "too old".

Field Summary

Fields

Modifier and Type	Field and Description
static String	REGISTRY_CATALOGUE_V1_NAMESPACE_URI Official Registry API catalogue's namespace URI.

Method Summary

Modifier and Type	Method and Description
boolean	areHeisCoveredByCertificate(Collection<String> heiIds, Certificate clientCert) Check if given set of HEIs is completely covered by the given certificate.
boolean	areHeisCoveredByCertificate(String[] heiIds, Certificate clientCert) This is an alias of areHeisCoveredByCertificate(Collection, Certificate).
boolean	areHeisCoveredByClientKey(Collection<String> heiIds, RSAPublicKey clientKey) Check if given set of HEIs is completely covered by the given client key.
boolean	areHeisCoveredByClientKey(String[] heiIds, RSAPublicKey clientKey) This is an alias of areHeisCoveredByClientKey(Collection, RSAPublicKey).
void	assertApiIsCoveredByServerKey(Element apiElement, RSAPublicKey serverKey) Performs the same action as described by isApiCoveredByServerKey(Element, RSAPublicKey), but throws an exception instead of returning booleans.
void	assertCertificateIsKnown(Certificate clientCert) Performs the same action as described by isCertificateKnown(Certificate), but throws an exception instead of returning booleans.
void	assertClientKeyIsKnown(RSAPublicKey clientKey) Performs the same action as described by isClientKeyKnown(RSAPublicKey), but throws an exception instead of returning booleans.
void	assertHeiIsCoveredByCertificate(String heiId, Certificate clientCert) Performs the same action as described by isHeiCoveredByCertificate(String, Certificate), but throws an exception instead of returning booleans.
void	assertHeiIsCoveredByClientKey(String heiId, RSAPublicKey clientKey) Performs the same action as described by isHeiCoveredByClientKey(String, RSAPublicKey) , but throws an exception instead of returning booleans.
void	assertHeisAreCoveredByCertificate(Collection<String> heiIds, Certificate clientCert) Performs the same action as described by areHeisCoveredByCertificate(Collection, Certificate), but throws an exception instead of returning booleans.
void	assertHeisAreCoveredByCertificate(String[] heiIds, Certificate clientCert) This is an alias of assertHeisAreCoveredByCertificate(Collection, Certificate).
void	assertHeisAreCoveredByClientKey(Collection<String> heiIds, RSAPublicKey clientKey) Performs the same action as described by areHeisCoveredByClientKey(Collection, RSAPublicKey), but throws an exception instead of returning booleans.
void	assertHeisAreCoveredByClientKey(String[] heiIds, RSAPublicKey clientKey) This is an alias of assertHeisAreCoveredByClientKey(Collection, RSAPublicKey).
void	close() Relinquish all underlying resources.
Element	findApi(ApiSearchConditions conditions) Find particular API implementation in the network.
Collection<Element>	findApis(ApiSearchConditions conditions) Find all API implementations matching the given conditions.
HeiEntry	findHei(String id) Retrieve a HeiEntry for a given HEI SCHAC ID.
HeiEntry	findHei(String type, String value) Find HeiEntry by other (non-SCHAC) ID.
String	findHeiId(String type, String value) Find the HEI's SCHAC ID by providing an other (non-SCHAC) type of ID.
Collection<HeiEntry>	findHeis(ApiSearchConditions conditions) Find HEIs for which a particular API has been implemented.
RSAPublicKey	findRsaPublicKey(String fingerprint) Find a public key identified by a given fingerprint.
Collection<HeiEntry>	getAllHeis() Retrieve a list of all HEIs described in the Registry's catalogue.
Date	getExpiryDate() Get the expiry date of the currently held copy of the catalogue.
Collection<String>	getHeisCoveredByCertificate(Certificate clientCert) Retrieve a list of HEIs covered by the given certificate.
Collection<String>	getHeisCoveredByClientKey(RSAPublicKey clientKey) Retrieve a list of HEIs covered by the given client key.
RSAPublicKey	getServerKeyCoveringApi(Element apiElement) Find a server key covering a given API.
Collection<RSAPublicKey>	getServerKeysCoveringApi(Element apiElement) Retrieve all server keys covering a given API.
boolean	isApiCoveredByServerKey(Element apiElement, RSAPublicKey serverKey) Check if a given API is covered by a given server key.
boolean	isCertificateKnown(Certificate clientCert) Check if a given client certificate is present in the Registry's catalogue.
boolean	isClientKeyKnown(RSAPublicKey clientKey) Check if a given client key is present in the Registry's catalogue.
boolean	isHeiCoveredByCertificate(String heiId, Certificate clientCert) Check if a given HEI is covered by a given client certificate.
boolean	isHeiCoveredByClientKey(String heiId, RSAPublicKey clientKey) Check if a given HEI is covered by a given client key.
void	refresh() Force the client to refresh its internal copy of the EWP catalogue.

Field Detail

REGISTRY_CATALOGUE_V1_NAMESPACE_URI

static final String REGISTRY_CATALOGUE_V1_NAMESPACE_URI

Official Registry API catalogue's namespace URI.

See Also:

Constant Field Values

Method Detail

areHeisCoveredByCertificate

boolean areHeisCoveredByCertificate(Collection<String> heiIds,
                                    Certificate clientCert)
                             throws RegistryClient.UnacceptableStalenessException

Check if given set of HEIs is completely covered by the given certificate.

In other words, check if each HEI on the list, is also present on the list of HEIs covered by this certificate (the latter list may still contain other HEIs too).

Parameters:

heiIds - the list HEI SCHAC IDs that need to be covered.

clientCert - as in isCertificateKnown(Certificate).

Returns:

true if all HEIs are covered by this certificate, false if at least one of them isn't, or if the certificate is not known.

Throws:

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException for more information.

areHeisCoveredByCertificate

boolean areHeisCoveredByCertificate(String[] heiIds,
                                    Certificate clientCert)
                             throws RegistryClient.UnacceptableStalenessException

This is an alias of areHeisCoveredByCertificate(Collection, Certificate). It just takes String[] instead of a collection.

Parameters:

heiIds - an array of HEI SCHAC IDs that need to be covered.

clientCert - as in isCertificateKnown(Certificate).

Returns:

true if all HEIs are covered by this certificate, false if at least one of them isn't, or if the certificate is not known.

Throws:

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException for more information.

areHeisCoveredByClientKey

boolean areHeisCoveredByClientKey(Collection<String> heiIds,
                                  RSAPublicKey clientKey)
                           throws RegistryClient.UnacceptableStalenessException

Check if given set of HEIs is completely covered by the given client key.

In other words, check if each HEI on the list, is also present on the list of HEIs covered by this client key (the latter list may still contain other HEIs too).

Parameters:

heiIds - the list HEI SCHAC IDs that need to be covered.

clientKey - as in isClientKeyKnown(RSAPublicKey).

Returns:

true if all HEIs are covered by this client key, false if at least one of them isn't, or if the client key is not known.

Throws:

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException for more information.

Since:

1.4.0

areHeisCoveredByClientKey

boolean areHeisCoveredByClientKey(String[] heiIds,
                                  RSAPublicKey clientKey)
                           throws RegistryClient.UnacceptableStalenessException

This is an alias of areHeisCoveredByClientKey(Collection, RSAPublicKey). It just takes String[] instead of a collection.

Parameters:

heiIds - an array of HEI SCHAC IDs that need to be covered.

clientKey - as in isClientKeyKnown(RSAPublicKey).

Returns:

true if all HEIs are covered by this client key, false if at least one of them isn't, or if the client key is not known.

Throws:

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException for more information.

Since:

1.4.0

assertApiIsCoveredByServerKey

void assertApiIsCoveredByServerKey(Element apiElement,
                                   RSAPublicKey serverKey)
                            throws RegistryClient.AssertionFailedException,
                                   RegistryClient.InvalidApiEntryElement,
                                   RegistryClient.UnacceptableStalenessException

Performs the same action as described by isApiCoveredByServerKey(Element, RSAPublicKey), but throws an exception instead of returning booleans.

Parameters:

apiElement - as in isApiCoveredByServerKey(Element, RSAPublicKey).

serverKey - as in isApiCoveredByServerKey(Element, RSAPublicKey).

Throws:

RegistryClient.AssertionFailedException - if this API is not covered by this server key.

RegistryClient.InvalidApiEntryElement - as in isApiCoveredByServerKey(Element, RSAPublicKey).

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException for more information.

Since:

1.5.0

assertCertificateIsKnown

void assertCertificateIsKnown(Certificate clientCert)
                       throws RegistryClient.AssertionFailedException,
                              RegistryClient.UnacceptableStalenessException

Performs the same action as described by isCertificateKnown(Certificate), but throws an exception instead of returning booleans.

Parameters:

clientCert - as in isCertificateKnown(Certificate).

Throws:

RegistryClient.AssertionFailedException - if this certificate has not been listed in the Registry's catalogue.

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException for more information.

assertClientKeyIsKnown

void assertClientKeyIsKnown(RSAPublicKey clientKey)
                     throws RegistryClient.AssertionFailedException,
                            RegistryClient.UnacceptableStalenessException

Performs the same action as described by isClientKeyKnown(RSAPublicKey), but throws an exception instead of returning booleans.

Parameters:

clientKey - as in isClientKeyKnown(RSAPublicKey).

Throws:

RegistryClient.AssertionFailedException - if this client key has not been listed in the Registry's catalogue.

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException for more information.

Since:

1.4.0

assertHeiIsCoveredByCertificate

void assertHeiIsCoveredByCertificate(String heiId,
                                     Certificate clientCert)
                              throws RegistryClient.AssertionFailedException,
                                     RegistryClient.UnacceptableStalenessException

Performs the same action as described by isHeiCoveredByCertificate(String, Certificate), but throws an exception instead of returning booleans.

Parameters:

heiId - as in isHeiCoveredByCertificate(String, Certificate).

clientCert - as in isHeiCoveredByCertificate(String, Certificate).

Throws:

RegistryClient.AssertionFailedException - if the HEI is not covered by this certificate, or the certificate is not known.

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException for more information.

assertHeiIsCoveredByClientKey

void assertHeiIsCoveredByClientKey(String heiId,
                                   RSAPublicKey clientKey)
                            throws RegistryClient.AssertionFailedException,
                                   RegistryClient.UnacceptableStalenessException

Performs the same action as described by isHeiCoveredByClientKey(String, RSAPublicKey) , but throws an exception instead of returning booleans.

Parameters:

heiId - as in isHeiCoveredByClientKey(String, RSAPublicKey).

clientKey - as in isHeiCoveredByClientKey(String, RSAPublicKey).

Throws:

RegistryClient.AssertionFailedException - if the HEI is not covered by this client key, or the client key is not known.

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException for more information.

Since:

1.4.0

assertHeisAreCoveredByCertificate

void assertHeisAreCoveredByCertificate(Collection<String> heiIds,
                                       Certificate clientCert)
                                throws RegistryClient.AssertionFailedException,
                                       RegistryClient.UnacceptableStalenessException

Performs the same action as described by areHeisCoveredByCertificate(Collection, Certificate), but throws an exception instead of returning booleans.

Parameters:

heiIds - as in areHeisCoveredByCertificate(Collection, Certificate).

clientCert - as in areHeisCoveredByCertificate(Collection, Certificate).

Throws:

RegistryClient.AssertionFailedException - if at least one of the HEIs is not covered by the certificate, or the certificate is not known.

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException for more information.

assertHeisAreCoveredByCertificate

void assertHeisAreCoveredByCertificate(String[] heiIds,
                                       Certificate clientCert)
                                throws RegistryClient.AssertionFailedException,
                                       RegistryClient.UnacceptableStalenessException

This is an alias of assertHeisAreCoveredByCertificate(Collection, Certificate). It just takes String[] instead of a collection.

Parameters:

heiIds - as in areHeisCoveredByCertificate(String[], Certificate).

clientCert - as in areHeisCoveredByCertificate(String[], Certificate).

Throws:

RegistryClient.AssertionFailedException - if at least one of the HEIs is not covered by the certificate, or the certificate is not known.

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException for more information.

assertHeisAreCoveredByClientKey

void assertHeisAreCoveredByClientKey(Collection<String> heiIds,
                                     RSAPublicKey clientKey)
                              throws RegistryClient.AssertionFailedException,
                                     RegistryClient.UnacceptableStalenessException

Performs the same action as described by areHeisCoveredByClientKey(Collection, RSAPublicKey), but throws an exception instead of returning booleans.

Parameters:

heiIds - as in areHeisCoveredByClientKey(Collection, RSAPublicKey).

clientKey - as in areHeisCoveredByClientKey(Collection, RSAPublicKey).

Throws:

RegistryClient.AssertionFailedException - if at least one of the HEIs is not covered by the client key, or the client key is not known.

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException for more information.

Since:

1.4.0

assertHeisAreCoveredByClientKey

void assertHeisAreCoveredByClientKey(String[] heiIds,
                                     RSAPublicKey clientKey)
                              throws RegistryClient.AssertionFailedException,
                                     RegistryClient.UnacceptableStalenessException

This is an alias of assertHeisAreCoveredByClientKey(Collection, RSAPublicKey). It just takes String[] instead of a collection.

Parameters:

heiIds - as in areHeisCoveredByClientKey(String[], RSAPublicKey).

clientKey - as in areHeisCoveredByClientKey(String[], RSAPublicKey).

Throws:

RegistryClient.AssertionFailedException - if at least one of the HEIs is not covered by the client key, or the client key is not known.

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException for more information.

Since:

1.4.0

close

void close()

Relinquish all underlying resources.

You should call this once you don't need the RegistryClient anymore. Note that this is part of the AutoCloseable interface, so if you're using frameworks such as Spring then this might be called automatically (provided that you're using RegistryClient as a bean).

Specified by:

close in interface AutoCloseable

findApi

Element findApi(ApiSearchConditions conditions)
         throws RegistryClient.UnacceptableStalenessException

Find particular API implementation in the network.

If multiple matches are found, then this method will return the one that has the highest version attribute. This is valid in most cases, but you can use the findApis(ApiSearchConditions) method if you want to retrieve the full list of matching results.

The exact format of this API entry depends on the API's class (the one you set via ApiSearchConditions.setApiClassRequired(String, String)). In case of primary EWP APIs, their API entries are described in manifest-entry.xsd files placed in along with the API specs in GitHub. Keep in mind, that the Registry Service is not required to validate the XSDs of all of the API entries it serves (especially if the API is not related to the original EWP project). This means that you might want to validate this element yourself, before using it.

You SHOULD NOT keep references to API entry elements for longer use. You SHOULD acquire fresh copies directly before you need it. Elements MAY contain internal RegistryClient data, and keeping them might cause memory leaks. See here: https://github.com/erasmus-without-paper/ewp-registry-client/issues/8

Parameters:

conditions - Describes the conditions to search for.

Returns:

An XML DOM Element with the API entry, exactly as the were served by the Registry Service.

Throws:

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException for more information.

findApis

Collection<Element> findApis(ApiSearchConditions conditions)
                      throws RegistryClient.UnacceptableStalenessException

Find all API implementations matching the given conditions.

This works the same as findApi(ApiSearchConditions) does, but it returns a collection of all matched API entry elements, instead of just "the best one".

You SHOULD NOT keep references to API entry elements for longer use. You SHOULD acquire fresh copies directly before you need it. Elements MAY contain internal RegistryClient data, and keeping them might cause memory leaks. See here: https://github.com/erasmus-without-paper/ewp-registry-client/issues/8

Parameters:

conditions - as in findApi(ApiSearchConditions).

Returns:

a collection of XML DOM Elements with API entries, exactly as they were served by the Registry Service. Please read the notes in findApi(ApiSearchConditions) too.

Throws:

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException for more information.

findHei

HeiEntry findHei(String id)
          throws RegistryClient.UnacceptableStalenessException

Retrieve a HeiEntry for a given HEI SCHAC ID.

Parameters:

id - HEI's SCHAC ID. If you don't have a SCHAC ID, then take a look at findHei(String, String) and findHeiId(String, String).

Returns:

HeiEntry, or null if no such HEI has been found.

Throws:

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException for more information.

Since:

1.2.0

findHei

HeiEntry findHei(String type,
                 String value)
          throws RegistryClient.UnacceptableStalenessException

Find HeiEntry by other (non-SCHAC) ID.

EWP Network uses SCHAC IDs as primary HEI IDs (if you know a SCHAC ID, then you should use the findHei(String) method instead of this one). However, Registry Service also keeps a mapping of various other popular types of HEI IDs and allows you to translate them to SCHAC IDs. (You can use this method, for example, to periodically populate your database fields with SCHAC IDs.)

Parameters:

type - This can be any string, but in most cases you will use "pic", "erasmus" or "previous-schac" here. Check the current version of the catalogue.xsd file in the Registry API specification for more identifiers.

value - The searched value (e.g. if you have provided "pic" in type argument, then this should be the PIC code of the HEI being searched for). Note, that RegistryClient implementations are allowed to transform your input slightly (e.g. remove whitespace, or ignore the case) before the matching occurs.

Returns:

HeiEntry, or null if no matching HEI has been found.

Throws:

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException for more information.

Since:

1.2.0

findHeiId

String findHeiId(String type,
                 String value)
          throws RegistryClient.UnacceptableStalenessException

Find the HEI's SCHAC ID by providing an other (non-SCHAC) type of ID.

This is equivalent to calling findHei(String, String) and then retrieving ID from it.

Parameters:

type - as in findHei(String, String).

value - as in findHei(String, String).

Returns:

Either String or null. String with a valid SCHAC ID of this HEI is returned, if a matching HEI was found. If no match was found, null is returned.

Throws:

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException for more information.

findHeis

Collection<HeiEntry> findHeis(ApiSearchConditions conditions)
                       throws RegistryClient.UnacceptableStalenessException

Find HEIs for which a particular API has been implemented.

Example

The following call will return all HEIs which have implemented EWP's Echo API in version 1.0.1 or later:

 ApiSearchConditions myEchoConditions = new ApiSearchConditions();
 String ns = "https://github.com/erasmus-without-paper/"
     + "ewp-specs-api-echo/blob/stable-v1/manifest-entry.xsd";
 myEchoConditions.setApiClassRequired(ns, "echo", "1.0.1");
 Collection<HeiEntry> heis = client.findHeis(myEchoConditions);
 

The above gives you HEIs, but not Echo API URLs. In order to get those, you will need to call findApi(ApiSearchConditions) later on (with revised ApiSearchConditions).

Parameters:

conditions - Describes the conditions which at least one of the HEIs' APIs must meet.

Returns:

A list of matching HeiEntry objects.

Throws:

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException for more information.

Since:

1.2.0

findRsaPublicKey

RSAPublicKey findRsaPublicKey(String fingerprint)
                       throws RegistryClient.UnacceptableStalenessException

Find a public key identified by a given fingerprint.

Please note, that the mere fact of finding the key in the Registry's catalogue, tells you nothing about the owner, nor the permissions of this key. If you manage to find the key, then in most cases you still need to call some other methods (such as assertHeiIsCoveredByClientKey(String, RSAPublicKey) or isApiCoveredByServerKey(Element, RSAPublicKey)), in order to verify the key.

Parameters:

fingerprint - HEX-encoded SHA-256 fingerprint of the public key.

If you're using EWP's HTTP Signature client/server authentication methods, then this value is taken from the keyId parameter passed in Authorization or Signature header.

Returns:

Either RSAPublicKey or null (if no such key was found in the Registry).

Throws:

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException for more information.

Since:

1.5.0

getAllHeis

Collection<HeiEntry> getAllHeis()
                         throws RegistryClient.UnacceptableStalenessException

Retrieve a list of all HEIs described in the Registry's catalogue.

Note, that this list may contain HEIs which don't implement any API. If you want to find HEIs which implement particular API, then use findHeis(ApiSearchConditions) instead.

Returns:

A list of HeiEntry objects.

Throws:

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException for more information.

Since:

1.2.0

getExpiryDate

Date getExpiryDate()

Get the expiry date of the currently held copy of the catalogue.

Most RegistryClient implementations will hold a copy of the Registry's catalogue in memory between calls. Whenever a new copy of the catalogue is fetched, the expiry-date of this copy should be fetched along with it. You can use this method to retrieve this expiry date.

In general, this date should not be "too much" in the past. If it is, then most RegistryClient implementations (such as ClientImpl) will start to throw RegistryClient.UnacceptableStalenessException exceptions when other RegistryClient methods are called.

Returns:

The expiry date, as returned by the Registry Service when the currently held copy of the catalogue has been fetched.

getHeisCoveredByCertificate

Collection<String> getHeisCoveredByCertificate(Certificate clientCert)
                                        throws RegistryClient.UnacceptableStalenessException

Retrieve a list of HEIs covered by the given certificate.

Please note, that this list will also be empty if the certificate is unknown. Use assertCertificateIsKnown(Certificate) if you need to differentiate between these two scenarios.

Parameters:

clientCert - as in isCertificateKnown(Certificate).

Returns:

A list of HEI SCHAC IDs. May be empty.

Throws:

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException for more information.

getHeisCoveredByClientKey

Collection<String> getHeisCoveredByClientKey(RSAPublicKey clientKey)
                                      throws RegistryClient.UnacceptableStalenessException

Retrieve a list of HEIs covered by the given client key.

Please note, that this list will also be empty if the client key is unknown. Use assertClientKeyIsKnown(RSAPublicKey) if you need to differentiate between these two scenarios.

Parameters:

clientKey - as in isClientKeyKnown(RSAPublicKey).

Returns:

A list of HEI SCHAC IDs. May be empty.

Throws:

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException for more information.

Since:

1.4.0

getServerKeyCoveringApi

RSAPublicKey getServerKeyCoveringApi(Element apiElement)
                              throws RegistryClient.UnacceptableStalenessException,
                                     RegistryClient.InvalidApiEntryElement

Find a server key covering a given API.

This will be one of the keys returned be getServerKeysCoveringApi(Element). The method by which this element is chosen is not specified (i.e. it can be any of them).

This method might be useful if you are choosing a key for request encryption. On the other hand, if you are validating response signatures, then you probably should look at isApiCoveredByServerKey(Element, RSAPublicKey).

Parameters:

apiElement - The catalogue Element which describes the said API. This MUST be the same element which you have previously gotten from findApi(ApiSearchConditions) or findApis(ApiSearchConditions) method.

Returns:

RSAPublicKey, or null if no covering server key was found.

Throws:

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException for more information.

RegistryClient.InvalidApiEntryElement - if the apiElement you have provided doesn't seem to be a valid one (the one which has been produced by this RegistryClient).

Since:

1.6.0

getServerKeysCoveringApi

Collection<RSAPublicKey> getServerKeysCoveringApi(Element apiElement)
                                           throws RegistryClient.UnacceptableStalenessException,
                                                  RegistryClient.InvalidApiEntryElement

Retrieve all server keys covering a given API.

You might want to use this method instead of getServerKeyCoveringApi(Element), if you don't want just any of the keys, and prefer to choose the key by yourself.

Parameters:

apiElement - The catalogue Element which describes the said API. This MUST be the same element which you have previously gotten from findApi(ApiSearchConditions) or findApis(ApiSearchConditions) method.

Returns:

A list of RSAPublicKey instances. May be empty.

Throws:

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException for more information.

RegistryClient.InvalidApiEntryElement - if the apiElement you have provided doesn't seem to be a valid one (the one which has been produced by this RegistryClient).

Since:

1.6.0

isApiCoveredByServerKey

boolean isApiCoveredByServerKey(Element apiElement,
                                RSAPublicKey serverKey)
                         throws RegistryClient.UnacceptableStalenessException,
                                RegistryClient.InvalidApiEntryElement

Check if a given API is covered by a given server key.

Parameters:

apiElement - The catalogue Element which describes the said API. This MUST be the same element which you have previously gotten from findApi(ApiSearchConditions) or findApis(ApiSearchConditions) method.

serverKey - The key which you want to check (if the API is indeed covered by this key).

Returns:

true if this API is indeed covered by this server key, false otherwise.

Throws:

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException for more information.

RegistryClient.InvalidApiEntryElement - if the apiElement you have provided doesn't seem to be a valid one (the one which has been produced by this RegistryClient).

Since:

1.4.0

isCertificateKnown

boolean isCertificateKnown(Certificate clientCert)
                    throws RegistryClient.UnacceptableStalenessException

Check if a given client certificate is present in the Registry's catalogue.

You can use this method when you are developing an EWP API endpoint, and you want to make sure that it will be accessible only to the requesters within the EWP Network.

Parameters:

clientCert - a valid certificate (if it's not valid, you'll get RuntimeExceptions). Most often, this will be the certificate which the requester have used in his HTTPS request).

Returns:

true if this certificate belongs to someone from the EWP Network.

Throws:

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException.

See Also:

getHeisCoveredByCertificate(Certificate), isHeiCoveredByCertificate(String, Certificate)

isClientKeyKnown

boolean isClientKeyKnown(RSAPublicKey clientKey)
                  throws RegistryClient.UnacceptableStalenessException

Check if a given client key is present in the Registry's catalogue.

You can use this method when you are developing an EWP API endpoint, and you want to make sure that it will be accessible only to the requesters within the EWP Network.

Parameters:

clientKey - a valid client public key (if it's not valid, you'll get RuntimeExceptions). Most often, this will be the public key which the requester has used in his request's HTTP signature).

Returns:

true if this client key belongs to someone from the EWP Network.

Throws:

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException.

Since:

1.4.0

See Also:

getHeisCoveredByClientKey(RSAPublicKey), isHeiCoveredByClientKey(String, RSAPublicKey)

isHeiCoveredByCertificate

boolean isHeiCoveredByCertificate(String heiId,
                                  Certificate clientCert)
                           throws RegistryClient.UnacceptableStalenessException

Check if a given HEI is covered by a given client certificate.

Parameters:

heiId - SCHAC ID of the HEI. If you do not know the HEI's SCHAC ID, you may attempt to find it with the help of findHeiId(String, String) method.

clientCert - as in isCertificateKnown(Certificate).

Returns:

true if the certificate is known, and HEI is covered by it. False otherwise.

Throws:

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException for more information.

isHeiCoveredByClientKey

boolean isHeiCoveredByClientKey(String heiId,
                                RSAPublicKey clientKey)
                         throws RegistryClient.UnacceptableStalenessException

Check if a given HEI is covered by a given client key.

Parameters:

heiId - SCHAC ID of the HEI. If you do not know the HEI's SCHAC ID, you may attempt to find it with the help of findHeiId(String, String) method.

clientKey - as in isClientKeyKnown(RSAPublicKey).

Returns:

true if the client key is known, and HEI is covered by it. False otherwise.

Throws:

RegistryClient.UnacceptableStalenessException - if the catalogue copy is "too old". See RegistryClient.UnacceptableStalenessException for more information.

Since:

1.4.0

refresh

void refresh()
      throws RegistryClient.RefreshFailureException

Force the client to refresh its internal copy of the EWP catalogue.

This method is synchronous - it will block until the catalogue is fully refreshed.

Note, that many RegistryClient implementations (such as ClientImpl, if called with proper ClientImplOptions) will be able to refresh their copy of the catalogue automatically (without the need of you calling this method).

Throws:

RegistryClient.RefreshFailureException - if the Registry Service cannot be contacted.