Package org.opensaml.saml.common.binding

# Class AbstractEndpointResolver<EndpointType extends Endpoint>

java.lang.Object
net.shibboleth.shared.component.AbstractInitializableComponent
net.shibboleth.shared.component.AbstractIdentifiedInitializableComponent
org.opensaml.saml.common.binding.AbstractEndpointResolver<EndpointType>

Type Parameters:
  `EndpointType` - type of endpoint

All Implemented Interfaces:
  `Component`, `DestructableComponent`, `IdentifiedComponent`, `InitializableComponent`, `Resolver<EndpointType,CriteriaSet>`, `EndpointResolver<EndpointType>`

Direct Known Subclasses:
  `DefaultEndpointResolver`

public abstract class AbstractEndpointResolver<EndpointType extends Endpoint> extends AbstractIdentifiedInitializableComponent implements EndpointResolver<EndpointType>
Base implementation that resolves and validates protocol/profile endpoints using a combination of supplied parameters and SAML metadata.

SAML metadata rules are followed for deriving candidate endpoints to evaluate. The base class implements only a subset of required functionality, then extracts a set of candidates from metadata if present, and delegates to a subclass to actually evaluate each one for acceptability.

The supported `Criterion` types and their use follows:

`EndpointCriterion` (required)
  Contains a "template" for the eventual `Endpoint`(s) to resolve that identifies at minimum the type of endpoint object (via schema type or element name) to resolve. It MAY contain other attributes that will be used in matching candidate endpoints for suitability, such as index, binding, location, etc. If so marked, it may also be resolved as a trusted endpoint without additional verification required.
`BestMatchLocationCriterion`
  Prioritizes endpoint whose Location matches the most characters of the input criterion location. Only applied to the `resolveSingle(CriteriaSet)` method.
`BindingCriterion`
  Ordered list of bindings to filter and sort the endpoints. This overrides the ordering from the metadata and possibly overrides the normal default endpoint in favor of higher-precedence bindings.
`RoleDescriptorCriterion`
  If present, provides access to the candidate endpoint(s) to attempt resolution against. Strictly optional, but if absent, the supplied endpoint (from `EndpointCriterion`) is returned as the sole result, whatever its completeness/usability, allowing for subclass validation.

Subclasses should override the {`doCheckEndpoint(CriteriaSet, Endpoint)` method to implement further criteria.

## Field Summary

Fields
Modifier and Type
Field
Description
`private boolean`
`inMetadataOrder`
Sorting rule for results.
`private org.slf4j.Logger`
`log`
Class logger.

## Constructor Summary

Constructors
Constructor
Description
`AbstractEndpointResolver()`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`private boolean`
`canUseRequestedEndpoint(EndpointCriterion<EndpointType> criterion)`
Optimize the case of resolving a single endpoint if a populated endpoint is supplied via criteria, and validation is unnecessary due to a signed request.
`protected boolean`
`doCheckEndpoint(CriteriaSet criteria, EndpointType endpoint)`
Apply the supplied criteria to a candidate endpoint to determine its suitability.
`private List<EndpointType>`
`getCandidatesFromMetadata(CriteriaSet criteria)`
Get a mutable list of endpoints of a given type found in the metadata role contained in a `RoleDescriptorCriterion` (or an empty list if no metadata exists).
`protected String`
`getLogPrefix()`
Return a prefix for logging messages for this component.
`boolean`
`isInMetadataOrder()`
Get whether the results should be sorted by metadata order or based on the order of bindings provided to the lookup.
`Iterable<EndpointType>`
`resolve(CriteriaSet criteria)`
`EndpointType`
`resolveSingle(CriteriaSet criteria)`
`void`
`setInMetadataOrder(boolean flag)`
Set whether the results should be sorted by metadata order or based on the order of bindings provided to the lookup.
`private List<EndpointType>`
`sortCandidates(List<Endpoint> candidates)`
Copy and sort the endpoints such that the default endpoint by SAML rules comes first.
`private EndpointCriterion<EndpointType>`
`validateCriteria(CriteriaSet criteria)`
Verify that the required `EndpointCriterion` is present.

### Methods inherited from class net.shibboleth.shared.component.AbstractIdentifiedInitializableComponent

`doInitialize, ensureId, getId, ifDestroyedThrowDestroyedComponentException, ifInitializedThrowUnmodifiabledComponentException, ifNotInitializedThrowUninitializedComponentException, setId`

### Methods inherited from class net.shibboleth.shared.component.AbstractInitializableComponent

`checkComponentActive, checkSetterPreconditions, destroy, doDestroy, initialize, isDestroyed, isInitialized`

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

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

## Field Details

### log

@Nonnull private org.slf4j.Logger log
Class logger.

### inMetadataOrder

private boolean inMetadataOrder
Sorting rule for results.

## Constructor Details

### AbstractEndpointResolver

public AbstractEndpointResolver()
Constructor.

## Method Details

### isInMetadataOrder

public boolean isInMetadataOrder()
Get whether the results should be sorted by metadata order or based on the order of bindings provided to the lookup.

Returns:
  true iff the `BindingCriterion` should be ignored for the purposes of sorting the results
Since:
  4.1.0

### setInMetadataOrder

public void setInMetadataOrder(boolean flag)
Set whether the results should be sorted by metadata order or based on the order of bindings provided to the lookup.

Defaults to true

Parameters:
  `flag` - flag to set
Since:
  4.1.0

### resolve

@Nonnull public Iterable<EndpointType> resolve(@Nullable CriteriaSet criteria) throws ResolverException

Specified by:
  `resolve` in interface `Resolver<EndpointType extends Endpoint,CriteriaSet>`
Throws:
  `ResolverException`

### resolveSingle

@Nullable public EndpointType resolveSingle(@Nullable CriteriaSet criteria) throws ResolverException

Specified by:
  `resolveSingle` in interface `Resolver<EndpointType extends Endpoint,CriteriaSet>`
Throws:
  `ResolverException`

### doCheckEndpoint

protected boolean doCheckEndpoint(@Nonnull CriteriaSet criteria, @Nonnull EndpointType endpoint)
Apply the supplied criteria to a candidate endpoint to determine its suitability.

Parameters:
  `criteria` - input criteria set
  `endpoint` - candidate endpoint
Returns:
  true iff the endpoint meets the supplied criteria

### validateCriteria

@Nonnull private EndpointCriterion<EndpointType> validateCriteria(@Nullable CriteriaSet criteria) throws ResolverException
Verify that the required `EndpointCriterion` is present.

Parameters:
  `criteria` - input criteria set
Returns:
  the `EndpointCriterion`
Throws:
  `ResolverException` - if the input set is null or no `EndpointCriterion` is present

### canUseRequestedEndpoint

private boolean canUseRequestedEndpoint(@Nonnull EndpointCriterion<EndpointType> criterion)
Optimize the case of resolving a single endpoint if a populated endpoint is supplied via criteria, and validation is unnecessary due to a signed request. Note that this endpoint may turn out to be unusable by the caller, but that's immaterial because the requester must have dictated the binding and location, so we're not allowed to ignore that.

Parameters:
  `criterion` - the input `EndpointCriterion`
Returns:
  true iff the supplied endpoint via `EndpointCriterion` should be returned

### getCandidatesFromMetadata

@Nonnull private List<EndpointType> getCandidatesFromMetadata(@Nonnull CriteriaSet criteria)
Get a mutable list of endpoints of a given type found in the metadata role contained in a `RoleDescriptorCriterion` (or an empty list if no metadata exists).

The endpoint type to extract is based on the candidate endpoint in an `EndpointCriterion`. If the endpoints are indexed, the first list entry will contain the default endpoint to use in the absence of other limiting criteria.

Parameters:
  `criteria` - input criteria set
Returns:
  mutable list of endpoints from the metadata

### sortCandidates

@Nonnull private List<EndpointType> sortCandidates(@Nonnull List<Endpoint> candidates)
Copy and sort the endpoints such that the default endpoint by SAML rules comes first.

Parameters:
  `candidates` - input list of endpoints
Returns:
  a new list containing the endpoints such that the default is first

### getLogPrefix

@Nonnull protected String getLogPrefix()
Return a prefix for logging messages for this component.

Returns:
  a string for insertion at the beginning of any log messages