eu.erasmuswithoutpaper.registryclient

Class ClientImpl

java.lang.Object

eu.erasmuswithoutpaper.registryclient.ClientImpl

All Implemented Interfaces:

RegistryClient, AutoCloseable

public class ClientImpl
extends Object
implements RegistryClient

A thread-safe RegistryClient implementation with in-memory catalogue copy and background synchronization options.

• ClientImpl keeps a copy of the Registry's catalogue in memory, and thus allows all API queries to return immediately (without the need to query the remote server in the same thread).
• The in-memory copy of the catalogue can be refreshed both manually and automatically (see ClientImplOptions.setAutoRefreshing(boolean) for details).

Example 1: Use it as an @Autowired Spring bean

If you're using Spring or a similar IOT container, then you can use this client as a singleton bean:

 @Bean
 public RegistryClient getEwpRegistryClient() {
   ClientImplOptions options = new ClientImplOptions();
   options.setAutoRefreshing(true);
   return new ClientImpl(options);
 }
 

If you believe that you won't be using the client much (and you don't want to keep it in memory all the time), then you can also use a different scope for your bean (e.g. @Scope("request")). In such cases however, it is recommended to supply a ClientImplOptions.setPersistentCacheMap(Map) to speed up initialization.

Note: Spring will automatically call close() on AutoCloseable beans, so you don't need to call it yourself.

Example 2: Use it in-line

When used in-line, remember to wrap it in try-with-resources statement (or remember to call close() manually). It is recommended to supply ClientImplOptions.setPersistentCacheMap(Map) in your options:

 ClientImplOptions options = new ClientImplOptions();
 options.setAutoRefreshing(true);
 options.setPersistentCacheMap(...); // e.g. memcached server
 try (RegistryClient client = new ClientImpl(options)) {
   // Your queries.
 }
 

This approach is rather discouraged because the catalogue does not reside in memory between runs, and needs to be parsed before each use. It's also more susceptible to suffer from possible Registry Service downtime. It may however have its merits if you're planning to use the Registry only rarely.

Since:

1.0.0

Nested Class Summary

Nested classes/interfaces inherited from interface eu.erasmuswithoutpaper.registryclient.RegistryClient

RegistryClient.AssertionFailedException, RegistryClient.InvalidApiEntryElement, RegistryClient.RefreshFailureException, RegistryClient.RegistryClientException, RegistryClient.RegistryClientRuntimeException, RegistryClient.StaleApiEntryElement, RegistryClient.UnacceptableStalenessException

Field Summary

Fields inherited from interface eu.erasmuswithoutpaper.registryclient.RegistryClient

REGISTRY_CATALOGUE_V1_NAMESPACE_URI

Constructor Summary

Constructors

Constructor and Description
ClientImpl() Construct ClientImpl with default ClientImplOptions.
ClientImpl(ClientImplOptions options) Construct ClientImpl.

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 RegistryClient.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 RegistryClient.areHeisCoveredByClientKey(Collection, RSAPublicKey).
void	assertApiIsCoveredByServerKey(Element apiElement, RSAPublicKey serverKey) Performs the same action as described by RegistryClient.isApiCoveredByServerKey(Element, RSAPublicKey), but throws an exception instead of returning booleans.
void	assertCertificateIsKnown(Certificate clientCert) Performs the same action as described by RegistryClient.isCertificateKnown(Certificate), but throws an exception instead of returning booleans.
void	assertClientKeyIsKnown(RSAPublicKey clientKey) Performs the same action as described by RegistryClient.isClientKeyKnown(RSAPublicKey), but throws an exception instead of returning booleans.
void	assertHeiIsCoveredByCertificate(String heiId, Certificate clientCert) Performs the same action as described by RegistryClient.isHeiCoveredByCertificate(String, Certificate), but throws an exception instead of returning booleans.
void	assertHeiIsCoveredByClientKey(String heiId, RSAPublicKey clientKey) Performs the same action as described by RegistryClient.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 RegistryClient.areHeisCoveredByCertificate(Collection, Certificate), but throws an exception instead of returning booleans.
void	assertHeisAreCoveredByCertificate(String[] heiIds, Certificate clientCert) This is an alias of RegistryClient.assertHeisAreCoveredByCertificate(Collection, Certificate).
void	assertHeisAreCoveredByClientKey(Collection<String> heiIds, RSAPublicKey clientKey) Performs the same action as described by RegistryClient.areHeisCoveredByClientKey(Collection, RSAPublicKey), but throws an exception instead of returning booleans.
void	assertHeisAreCoveredByClientKey(String[] heiIds, RSAPublicKey clientKey) This is an alias of RegistryClient.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.

Methods inherited from class java.lang.Object

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

Constructor Detail

ClientImpl

public ClientImpl()

Construct ClientImpl with default ClientImplOptions.

ClientImpl

public ClientImpl(ClientImplOptions options)

Construct ClientImpl.

Parameters:

options - Options to use. These options cannot be changed after the constructor is called (if they do, then behavior will be undetermined).

Method Detail

areHeisCoveredByCertificate

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

Description copied from interface: RegistryClient

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).

Specified by:

areHeisCoveredByCertificate in interface RegistryClient

Parameters:

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

clientCert - as in RegistryClient.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

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

Description copied from interface: RegistryClient

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

Specified by:

areHeisCoveredByCertificate in interface RegistryClient

Parameters:

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

clientCert - as in RegistryClient.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

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

Description copied from interface: RegistryClient

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).

Specified by:

areHeisCoveredByClientKey in interface RegistryClient

Parameters:

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

clientKey - as in RegistryClient.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.

areHeisCoveredByClientKey

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

Description copied from interface: RegistryClient

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

Specified by:

areHeisCoveredByClientKey in interface RegistryClient

Parameters:

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

clientKey - as in RegistryClient.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.

assertApiIsCoveredByServerKey

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

Description copied from interface: RegistryClient

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

Specified by:

assertApiIsCoveredByServerKey in interface RegistryClient

Parameters:

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

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

Throws:

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

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

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

assertCertificateIsKnown

public void assertCertificateIsKnown(Certificate clientCert)
                              throws RegistryClient.AssertionFailedException

Description copied from interface: RegistryClient

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

Specified by:

assertCertificateIsKnown in interface RegistryClient

Parameters:

clientCert - as in RegistryClient.isCertificateKnown(Certificate).

Throws:

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

assertClientKeyIsKnown

public void assertClientKeyIsKnown(RSAPublicKey clientKey)
                            throws RegistryClient.AssertionFailedException

Description copied from interface: RegistryClient

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

Specified by:

assertClientKeyIsKnown in interface RegistryClient

Parameters:

clientKey - as in RegistryClient.isClientKeyKnown(RSAPublicKey).

Throws:

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

assertHeiIsCoveredByCertificate

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

Description copied from interface: RegistryClient

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

Specified by:

assertHeiIsCoveredByCertificate in interface RegistryClient

Parameters:

heiId - as in RegistryClient.isHeiCoveredByCertificate(String, Certificate).

clientCert - as in RegistryClient.isHeiCoveredByCertificate(String, Certificate).

Throws:

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

assertHeiIsCoveredByClientKey

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

Description copied from interface: RegistryClient

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

Specified by:

assertHeiIsCoveredByClientKey in interface RegistryClient

Parameters:

heiId - as in RegistryClient.isHeiCoveredByClientKey(String, RSAPublicKey).

clientKey - as in RegistryClient.isHeiCoveredByClientKey(String, RSAPublicKey).

Throws:

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

assertHeisAreCoveredByCertificate

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

Description copied from interface: RegistryClient

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

Specified by:

assertHeisAreCoveredByCertificate in interface RegistryClient

Parameters:

heiIds - as in RegistryClient.areHeisCoveredByCertificate(Collection, Certificate).

clientCert - as in RegistryClient.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.

assertHeisAreCoveredByCertificate

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

Description copied from interface: RegistryClient

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

Specified by:

assertHeisAreCoveredByCertificate in interface RegistryClient

Parameters:

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

clientCert - as in RegistryClient.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.

assertHeisAreCoveredByClientKey

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

Description copied from interface: RegistryClient

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

Specified by:

assertHeisAreCoveredByClientKey in interface RegistryClient

Parameters:

heiIds - as in RegistryClient.areHeisCoveredByClientKey(Collection, RSAPublicKey).

clientKey - as in RegistryClient.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.

assertHeisAreCoveredByClientKey

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

Description copied from interface: RegistryClient

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

Specified by:

assertHeisAreCoveredByClientKey in interface RegistryClient

Parameters:

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

clientKey - as in RegistryClient.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.

close

public void close()

Description copied from interface: RegistryClient

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 RegistryClient

Specified by:

close in interface AutoCloseable

findApi

public Element findApi(ApiSearchConditions conditions)

Description copied from interface: RegistryClient

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 RegistryClient.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

Specified by:

findApi in interface RegistryClient

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.

findApis

public Collection<Element> findApis(ApiSearchConditions conditions)

Description copied from interface: RegistryClient

Find all API implementations matching the given conditions.

This works the same as RegistryClient.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

Specified by:

findApis in interface RegistryClient

Parameters:

conditions - as in RegistryClient.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 RegistryClient.findApi(ApiSearchConditions) too.

findHei

public HeiEntry findHei(String id)
                 throws RegistryClient.UnacceptableStalenessException

Description copied from interface: RegistryClient

Retrieve a HeiEntry for a given HEI SCHAC ID.

Specified by:

findHei in interface RegistryClient

Parameters:

id - HEI's SCHAC ID. If you don't have a SCHAC ID, then take a look at RegistryClient.findHei(String, String) and RegistryClient.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.

findHei

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

Description copied from interface: RegistryClient

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 RegistryClient.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.)

Specified by:

findHei in interface RegistryClient

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.

findHeiId

public String findHeiId(String type,
                        String value)

Description copied from interface: RegistryClient

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

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

Specified by:

findHeiId in interface RegistryClient

Parameters:

type - as in RegistryClient.findHei(String, String).

value - as in RegistryClient.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.

findHeis

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

Description copied from interface: RegistryClient

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 RegistryClient.findApi(ApiSearchConditions) later on (with revised ApiSearchConditions).

Specified by:

findHeis in interface RegistryClient

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.

findRsaPublicKey

public RSAPublicKey findRsaPublicKey(String fingerprint)
                              throws RegistryClient.UnacceptableStalenessException

Description copied from interface: RegistryClient

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 RegistryClient.assertHeiIsCoveredByClientKey(String, RSAPublicKey) or RegistryClient.isApiCoveredByServerKey(Element, RSAPublicKey)), in order to verify the key.

Specified by:

findRsaPublicKey in interface RegistryClient

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.

getAllHeis

public Collection<HeiEntry> getAllHeis()
                                throws RegistryClient.UnacceptableStalenessException

Description copied from interface: RegistryClient

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 RegistryClient.findHeis(ApiSearchConditions) instead.

Specified by:

getAllHeis in interface RegistryClient

Returns:

A list of HeiEntry objects.

Throws:

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

getExpiryDate

public Date getExpiryDate()

Description copied from interface: RegistryClient

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.

Specified by:

getExpiryDate in interface RegistryClient

Returns:

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

getHeisCoveredByCertificate

public Collection<String> getHeisCoveredByCertificate(Certificate clientCert)

Description copied from interface: RegistryClient

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 RegistryClient.assertCertificateIsKnown(Certificate) if you need to differentiate between these two scenarios.

Specified by:

getHeisCoveredByCertificate in interface RegistryClient

Parameters:

clientCert - as in RegistryClient.isCertificateKnown(Certificate).

Returns:

A list of HEI SCHAC IDs. May be empty.

getHeisCoveredByClientKey

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

Description copied from interface: RegistryClient

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 RegistryClient.assertClientKeyIsKnown(RSAPublicKey) if you need to differentiate between these two scenarios.

Specified by:

getHeisCoveredByClientKey in interface RegistryClient

Parameters:

clientKey - as in RegistryClient.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.

getServerKeyCoveringApi

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

Description copied from interface: RegistryClient

Find a server key covering a given API.

This will be one of the keys returned be RegistryClient.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 RegistryClient.isApiCoveredByServerKey(Element, RSAPublicKey).

Specified by:

getServerKeyCoveringApi in interface RegistryClient

Parameters:

apiElement - The catalogue Element which describes the said API. This MUST be the same element which you have previously gotten from RegistryClient.findApi(ApiSearchConditions) or RegistryClient.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).

getServerKeysCoveringApi

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

Description copied from interface: RegistryClient

Retrieve all server keys covering a given API.

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

Specified by:

getServerKeysCoveringApi in interface RegistryClient

Parameters:

apiElement - The catalogue Element which describes the said API. This MUST be the same element which you have previously gotten from RegistryClient.findApi(ApiSearchConditions) or RegistryClient.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).

isApiCoveredByServerKey

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

Description copied from interface: RegistryClient

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

Specified by:

isApiCoveredByServerKey in interface RegistryClient

Parameters:

apiElement - The catalogue Element which describes the said API. This MUST be the same element which you have previously gotten from RegistryClient.findApi(ApiSearchConditions) or RegistryClient.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).

isCertificateKnown

public boolean isCertificateKnown(Certificate clientCert)

Description copied from interface: RegistryClient

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.

Specified by:

isCertificateKnown in interface RegistryClient

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.

See Also:

RegistryClient.getHeisCoveredByCertificate(Certificate), RegistryClient.isHeiCoveredByCertificate(String, Certificate)

isClientKeyKnown

public boolean isClientKeyKnown(RSAPublicKey clientKey)
                         throws RegistryClient.UnacceptableStalenessException

Description copied from interface: RegistryClient

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.

Specified by:

isClientKeyKnown in interface RegistryClient

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.

See Also:

RegistryClient.getHeisCoveredByClientKey(RSAPublicKey), RegistryClient.isHeiCoveredByClientKey(String, RSAPublicKey)

isHeiCoveredByCertificate

public boolean isHeiCoveredByCertificate(String heiId,
                                         Certificate clientCert)

Description copied from interface: RegistryClient

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

Specified by:

isHeiCoveredByCertificate in interface RegistryClient

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 RegistryClient.findHeiId(String, String) method.

clientCert - as in RegistryClient.isCertificateKnown(Certificate).

Returns:

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

isHeiCoveredByClientKey

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

Description copied from interface: RegistryClient

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

Specified by:

isHeiCoveredByClientKey in interface RegistryClient

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 RegistryClient.findHeiId(String, String) method.

clientKey - as in RegistryClient.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.

refresh

public void refresh()
             throws RegistryClient.RefreshFailureException

Description copied from interface: RegistryClient

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).

Specified by:

refresh in interface RegistryClient

Throws:

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