Package org.opensaml.saml.metadata.resolver.impl

# Class AbstractMetadataResolver

java.lang.Object
net.shibboleth.shared.component.AbstractInitializableComponent
net.shibboleth.shared.component.AbstractIdentifiedInitializableComponent
net.shibboleth.shared.component.AbstractIdentifiableInitializableComponent
org.opensaml.saml.metadata.resolver.impl.AbstractMetadataResolver

All Implemented Interfaces:
  `Component`, `DestructableComponent`, `IdentifiableComponent`, `IdentifiedComponent`, `InitializableComponent`, `Resolver<EntityDescriptor,CriteriaSet>`, `MetadataResolver`

Direct Known Subclasses:
  `AbstractBatchMetadataResolver`, `AbstractDynamicMetadataResolver`

public abstract class AbstractMetadataResolver extends AbstractIdentifiableInitializableComponent implements MetadataResolver
An abstract, base, implementation of a metadata provider.

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`protected class`
`AbstractMetadataResolver.EntityBackingStore`
The collection of data which provides the backing store for the processed metadata.

## Field Summary

Fields
Modifier and Type
Field
Description
`private Predicate<ProfileRequestContext>`
`activationCondition`
Activation condition.
`private CriterionPredicateRegistry<EntityDescriptor>`
`criterionPredicateRegistry`
Registry used in resolving predicates from criteria.
`private AbstractMetadataResolver.EntityBackingStore`
`entityBackingStore`
Backing store for runtime EntityDescriptor data.
`private boolean`
`failFastInitialization`
Whether problems during initialization should cause the provider to fail or go on without metadata.
`private final org.slf4j.Logger`
`log`
Class logger.
`private String`
`logPrefix`
Logging prefix.
`private MetadataFilter`
`mdFilter`
Filter applied to all metadata.
`private String`
`metricsBaseName`
Base name for Metrics instrumentation names.
`private ParserPool`
`parser`
Pool of parsers used to process XML.
`private boolean`
`requireValidMetadata`
Whether metadata is required to be valid.
`private String`
`resolverType`
Resolver type.
`private boolean`
`satisfyAnyPredicates`
Flag which determines whether predicates used in filtering are connected by a logical 'OR' (true) or by logical 'AND' (false).
`private UnmarshallerFactory`
`unmarshallerFactory`
Unmarshaller factory used to get an unmarshaller for the metadata DOM.
`private boolean`
`useDefaultPredicateRegistry`
Flag which determines whether the default predicate registry will be used if one is not supplied explicitly.

## Constructor Summary

Constructors
Constructor
Description
`AbstractMetadataResolver()`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`protected AbstractMetadataResolver.EntityBackingStore`
`createNewBackingStore()`
Create a new backing store instance for EntityDescriptor data.
`protected void`
`doDestroy()`
`protected final void`
`doInitialize()`
`protected abstract Iterable<EntityDescriptor>`
`doResolve(CriteriaSet criteria)`
Subclasses should override this method.
`protected AbstractMetadataResolver.EntityBackingStore`
`ensureBackingStore()`
Get the EntityDescriptor backing store currently in use by the metadata resolver, raising a `ConstraintViolationException` if null.
`protected XMLObject`
`filterMetadata(XMLObject metadata)`
Filters the given metadata.
`Predicate<ProfileRequestContext>`
`getActivationCondition()`
Get an activation condition for this resolver.
`protected AbstractMetadataResolver.EntityBackingStore`
`getBackingStore()`
Get the EntityDescriptor backing store currently in use by the metadata resolver.
`CriterionPredicateRegistry<EntityDescriptor>`
`getCriterionPredicateRegistry()`
Get the registry used in resolving predicates from criteria.
`protected String`
`getLogPrefix()`
Return a prefix for logging messages for this component.
`MetadataFilter`
`getMetadataFilter()`
Gets the metadata filter applied to the metadata.
`String`
`getMetricsBaseName()`
Get the base name for Metrics instrumentation.
`ParserPool`
`getParserPool()`
Gets the pool of parsers to use to parse XML.
`String`
`getType()`
Gets the type of resolver for reporting or logging purposes.
`protected UnmarshallerFactory`
`getUnmarshallerFactory()`
Get the XMLObject unmarshaller factory to use.
`protected void`
`indexEntityDescriptor(EntityDescriptor entityDescriptor, AbstractMetadataResolver.EntityBackingStore backingStore)`
Index the specified entity descriptor, updating the specified entity backing store instance as necessary.
`protected void`
`initMetadataResolver()`
Subclasses should override this method to perform any initialization logic necessary.
`boolean`
`isFailFastInitialization()`
Gets whether problems during initialization should cause the provider to fail or go on without metadata.
`boolean`
`isRequireValidMetadata()`
Gets whether the metadata returned by queries must be valid.
`boolean`
`isSatisfyAnyPredicates()`
Get the flag indicating whether resolved credentials may satisfy any predicates (i.e.
`boolean`
`isUseDefaultPredicateRegistry()`
Get the flag which determines whether the default predicate registry will be used if one is not supplied explicitly.
`protected boolean`
`isValid(XMLObject descriptor)`
Returns whether the given descriptor is valid.
`protected List<EntityDescriptor>`
`lookupEntityID(String entityID)`
Get list of descriptors matching an entityID.
`protected List<EntityDescriptor>`
`lookupIndexedEntityID(String entityID)`
Lookup the specified entityID from the index.
`protected MetadataFilterContext`
`newFilterContext()`
Get a new instance of `MetadataFilterContext` to be used when filtering metadata.
`protected Iterable<EntityDescriptor>`
`predicateFilterCandidates(Iterable<EntityDescriptor> candidates, CriteriaSet criteria, boolean onEmptyPredicatesReturnEmpty)`
Filter the supplied candidates by resolving predicates from the supplied criteria and applying the predicates to return a filtered `Iterable`.
`protected void`
`preProcessEntitiesDescriptor(EntitiesDescriptor entitiesDescriptor, AbstractMetadataResolver.EntityBackingStore backingStore)`
Pre-process the specified entities descriptor, updating the specified entity backing store instance as necessary.
`protected void`
`preProcessEntityDescriptor(EntityDescriptor entityDescriptor, AbstractMetadataResolver.EntityBackingStore backingStore)`
Pre-process the specified entity descriptor, updating the specified entity backing store instance as necessary.
`protected void`
`releaseMetadataDOM(XMLObject metadata)`
Releases the DOM representation from the metadata object.
`protected void`
`removeByEntityID(String entityID, AbstractMetadataResolver.EntityBackingStore backingStore)`
Remove from the backing store all metadata for the entity with the given entity ID.
`Iterable<EntityDescriptor>`
`resolve(CriteriaSet criteria)`
`EntityDescriptor`
`resolveSingle(CriteriaSet criteria)`
`void`
`setActivationCondition(Predicate<ProfileRequestContext> condition)`
Set an activation condition for this resolver.
`protected void`
`setBackingStore(AbstractMetadataResolver.EntityBackingStore newBackingStore)`
Set the EntityDescriptor backing store currently in use by the metadata resolver.
`void`
`setCriterionPredicateRegistry(CriterionPredicateRegistry<EntityDescriptor> registry)`
Set the registry used in resolving predicates from criteria.
`void`
`setFailFastInitialization(boolean failFast)`
Sets whether problems during initialization should cause the provider to fail or go on without metadata.
`void`
`setMetadataFilter(MetadataFilter newFilter)`
Sets the metadata filter applied to the metadata.
`void`
`setMetricsBaseName(String baseName)`
Set the base name for Metrics instrumentation.
`void`
`setParserPool(ParserPool pool)`
Sets the pool of parsers to use to parse XML.
`void`
`setRequireValidMetadata(boolean require)`
Sets whether the metadata returned by queries must be valid.
`void`
`setSatisfyAnyPredicates(boolean flag)`
Set the flag indicating whether resolved credentials may satisfy any predicates (i.e.
`void`
`setType(String type)`
Sets the type of this resolver for reporting/logging.
`void`
`setUseDefaultPredicateRegistry(boolean flag)`
Set the flag which determines whether the default predicate registry will be used if one is not supplied explicitly.
`protected XMLObject`
`unmarshallMetadata(InputStream metadataInput)`
Unmarshalls the metadata from the given stream.

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

`setId`

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

`ensureId, getId, ifDestroyedThrowDestroyedComponentException, ifInitializedThrowUnmodifiabledComponentException, ifNotInitializedThrowUninitializedComponentException`

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

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

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

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

### Methods inherited from interface net.shibboleth.shared.component.IdentifiedComponent

`getId`

## Field Details

### log

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

### resolverType

@Nullable @NotEmpty private String resolverType
Resolver type.

### metricsBaseName

@NonnullAfterInit private String metricsBaseName
Base name for Metrics instrumentation names.

### unmarshallerFactory

@NonnullAfterInit private UnmarshallerFactory unmarshallerFactory
Unmarshaller factory used to get an unmarshaller for the metadata DOM.

### requireValidMetadata

private boolean requireValidMetadata
Whether metadata is required to be valid.

### mdFilter

@Nullable private MetadataFilter mdFilter
Filter applied to all metadata.

### logPrefix

@Nullable @NotEmpty private String logPrefix
Logging prefix.

### failFastInitialization

private boolean failFastInitialization
Whether problems during initialization should cause the provider to fail or go on without metadata. The assumption being that in most cases a provider will recover at some point in the future. Default: true.

### entityBackingStore

@Nullable private AbstractMetadataResolver.EntityBackingStore entityBackingStore
Backing store for runtime EntityDescriptor data.

### parser

@NonnullAfterInit private ParserPool parser
Pool of parsers used to process XML.

### satisfyAnyPredicates

private boolean satisfyAnyPredicates
Flag which determines whether predicates used in filtering are connected by a logical 'OR' (true) or by logical 'AND' (false). Defaults to false.

### criterionPredicateRegistry

@Nullable private CriterionPredicateRegistry<EntityDescriptor> criterionPredicateRegistry
Registry used in resolving predicates from criteria.

### useDefaultPredicateRegistry

private boolean useDefaultPredicateRegistry
Flag which determines whether the default predicate registry will be used if one is not supplied explicitly. Defaults to true.

### activationCondition

@Nullable private Predicate<ProfileRequestContext> activationCondition
Activation condition.

## Constructor Details

### AbstractMetadataResolver

public AbstractMetadataResolver()
Constructor.

## Method Details

### getType

@Nullable @NotEmpty public String getType()
Gets the type of resolver for reporting or logging purposes.

Specified by:
  `getType` in interface `MetadataResolver`
Returns:
  resolver type

### setType

public void setType(@Nullable @NotEmpty String type)
Sets the type of this resolver for reporting/logging.

Parameters:
  `type` - type to set
Since:
  5.0.0

### getMetricsBaseName

@NonnullAfterInit public String getMetricsBaseName()
Get the base name for Metrics instrumentation.

Returns:
  the Metrics base name
Since:
  5.0.0

### setMetricsBaseName

public void setMetricsBaseName(@Nullable String baseName)
Set the base name for Metrics instrumentation.

Parameters:
  `baseName` - the Metrics base name
Since:
  5.0.0

### isRequireValidMetadata

public boolean isRequireValidMetadata()
Gets whether the metadata returned by queries must be valid.

At a minimum, metadata is valid only if the date expressed in the `validUntil` attribute of the element and all its ancestral elements has not passed. Specific implementations may add additional constraints.

Specified by:
  `isRequireValidMetadata` in interface `MetadataResolver`
Returns:
  whether the metadata returned by queries must be valid

### setRequireValidMetadata

public void setRequireValidMetadata(boolean require)
Sets whether the metadata returned by queries must be valid.

Specified by:
  `setRequireValidMetadata` in interface `MetadataResolver`
Parameters:
  `require` - whether the metadata returned by queries must be valid

### getMetadataFilter

@Nullable public MetadataFilter getMetadataFilter()
Gets the metadata filter applied to the metadata.

Specified by:
  `getMetadataFilter` in interface `MetadataResolver`
Returns:
  the metadata filter applied to the metadata

### setMetadataFilter

public void setMetadataFilter(@Nullable MetadataFilter newFilter)
Sets the metadata filter applied to the metadata.

Specified by:
  `setMetadataFilter` in interface `MetadataResolver`
Parameters:
  `newFilter` - the metadata filter applied to the metadata

### isFailFastInitialization

public boolean isFailFastInitialization()
Gets whether problems during initialization should cause the provider to fail or go on without metadata. The assumption being that in most cases a provider will recover at some point in the future.

Returns:
  whether problems during initialization should cause the provider to fail

### setFailFastInitialization

public void setFailFastInitialization(boolean failFast)
Sets whether problems during initialization should cause the provider to fail or go on without metadata. The assumption being that in most cases a provider will recover at some point in the future.

Parameters:
  `failFast` - whether problems during initialization should cause the provider to fail

### getParserPool

@NonnullAfterInit public ParserPool getParserPool()
Gets the pool of parsers to use to parse XML.

Returns:
  pool of parsers to use to parse XML

### setParserPool

public void setParserPool(@Nonnull ParserPool pool)
Sets the pool of parsers to use to parse XML.

Parameters:
  `pool` - pool of parsers to use to parse XML

### isSatisfyAnyPredicates

public boolean isSatisfyAnyPredicates()
Get the flag indicating whether resolved credentials may satisfy any predicates (i.e. connected by logical 'OR') or all predicates (connected by logical 'AND').

Defaults to false.

Returns:
  true if must satisfy all, false otherwise

### setSatisfyAnyPredicates

public void setSatisfyAnyPredicates(boolean flag)
Set the flag indicating whether resolved credentials may satisfy any predicates (i.e. connected by logical 'OR') or all predicates (connected by logical 'AND').

Defaults to false.

Parameters:
  `flag` - true if must satisfy all, false otherwise

### getCriterionPredicateRegistry

@NonnullAfterInit public CriterionPredicateRegistry<EntityDescriptor> getCriterionPredicateRegistry()
Get the registry used in resolving predicates from criteria.

Returns:
  the effective registry instance used

### setCriterionPredicateRegistry

public void setCriterionPredicateRegistry(@Nullable CriterionPredicateRegistry<EntityDescriptor> registry)
Set the registry used in resolving predicates from criteria.

Parameters:
  `registry` - the registry instance to use

### isUseDefaultPredicateRegistry

public boolean isUseDefaultPredicateRegistry()
Get the flag which determines whether the default predicate registry will be used if one is not supplied explicitly.

Defaults to true.

Returns:
  true if should use default registry, false otherwise

### setUseDefaultPredicateRegistry

public void setUseDefaultPredicateRegistry(boolean flag)
Set the flag which determines whether the default predicate registry will be used if one is not supplied explicitly.

Defaults to true.

Parameters:
  `flag` - true if should use default registry, false otherwise

### getActivationCondition

@Nullable public Predicate<ProfileRequestContext> getActivationCondition()
Get an activation condition for this resolver.

Returns:
  activation condition

### setActivationCondition

public void setActivationCondition(@Nullable Predicate<ProfileRequestContext> condition)
Set an activation condition for this resolver.

Parameters:
  `condition` - condition to set

### resolveSingle

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

Specified by:
  `resolveSingle` in interface `Resolver<EntityDescriptor,CriteriaSet>`
Throws:
  `ResolverException`

### resolve

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

Specified by:
  `resolve` in interface `Resolver<EntityDescriptor,CriteriaSet>`
Throws:
  `ResolverException`

### doResolve

@Nonnull protected abstract Iterable<EntityDescriptor> doResolve(@Nullable CriteriaSet criteria) throws ResolverException
Subclasses should override this method.

Parameters:
  `criteria` - input criteria
Returns:
  resolution outcome
Throws:
  `ResolverException` - if an error occurs

### getUnmarshallerFactory

@NonnullAfterInit protected UnmarshallerFactory getUnmarshallerFactory()
Get the XMLObject unmarshaller factory to use.

Returns:
  the unmarshaller factory instance to use

### doInitialize

protected final void doInitialize() throws ComponentInitializationException

Overrides:
  `doInitialize` in class `AbstractIdentifiedInitializableComponent`
Throws:
  `ComponentInitializationException`

### doDestroy

protected void doDestroy()

Overrides:
  `doDestroy` in class `AbstractInitializableComponent`

### initMetadataResolver

protected void initMetadataResolver() throws ComponentInitializationException
Subclasses should override this method to perform any initialization logic necessary. Default implementation is a no-op.

Throws:
  `ComponentInitializationException` - thrown if there is a problem initializing the provider

### unmarshallMetadata

@Nonnull protected XMLObject unmarshallMetadata(@Nonnull InputStream metadataInput) throws UnmarshallingException
Unmarshalls the metadata from the given stream. The stream is closed by this method and the returned metadata released its DOM representation.

Parameters:
  `metadataInput` - the input reader to the metadata.
Returns:
  the unmarshalled metadata
Throws:
  `UnmarshallingException` - thrown if the metadata can no be unmarshalled

### filterMetadata

@Nullable protected XMLObject filterMetadata(@Nullable XMLObject metadata) throws FilterException
Filters the given metadata.

Parameters:
  `metadata` - the metadata to be filtered
Returns:
  the filtered metadata
Throws:
  `FilterException` - thrown if there is an error filtering the metadata

### newFilterContext

@Nonnull protected MetadataFilterContext newFilterContext()
Get a new instance of `MetadataFilterContext` to be used when filtering metadata.

This default implementation will just return an empty context. Subclasses would override to add contextual info specific to the implementation.

Returns:
  the new filter context instance

### releaseMetadataDOM

protected void releaseMetadataDOM(@Nullable XMLObject metadata)
Releases the DOM representation from the metadata object.

Parameters:
  `metadata` - the metadata object

### isValid

protected boolean isValid(@Nullable XMLObject descriptor)
Returns whether the given descriptor is valid. If valid metadata is not required this method always returns true.

Parameters:
  `descriptor` - the descriptor to check
Returns:
  true if valid metadata is not required or the given descriptor is valid, false otherwise

### lookupEntityID

@Nonnull protected List<EntityDescriptor> lookupEntityID(@Nonnull @NotEmpty String entityID) throws ResolverException
Get list of descriptors matching an entityID.

Parameters:
  `entityID` - entityID to lookup
Returns:
  a list of descriptors
Throws:
  `ResolverException` - if an error occurs

### lookupIndexedEntityID

@Nonnull protected List<EntityDescriptor> lookupIndexedEntityID(@Nonnull @NotEmpty String entityID)
Lookup the specified entityID from the index. The returned list will be a copy of what is stored in the backing index, and is safe to be manipulated by callers.

Parameters:
  `entityID` - the entityID to lookup
Returns:
  list copy of indexed entityID's, may be empty, will never be null

### createNewBackingStore

@Nonnull protected AbstractMetadataResolver.EntityBackingStore createNewBackingStore()
Create a new backing store instance for EntityDescriptor data. Subclasses may override to return a more specialized subclass type. Note this method does not make the returned backing store the effective one in use. The caller is responsible for calling `setBackingStore(EntityBackingStore)` to make it the effective instance in use.

Returns:
  the new backing store instance

### getBackingStore

@Nullable protected AbstractMetadataResolver.EntityBackingStore getBackingStore()
Get the EntityDescriptor backing store currently in use by the metadata resolver.

Returns:
  the current effective entity backing store

### ensureBackingStore

@Nonnull protected AbstractMetadataResolver.EntityBackingStore ensureBackingStore()
Get the EntityDescriptor backing store currently in use by the metadata resolver, raising a `ConstraintViolationException` if null.

Returns:
  the current effective entity backing store
Since:
  5.0.0

### setBackingStore

protected void setBackingStore(@Nonnull AbstractMetadataResolver.EntityBackingStore newBackingStore)
Set the EntityDescriptor backing store currently in use by the metadata resolver.

Parameters:
  `newBackingStore` - the new entity backing store

### preProcessEntityDescriptor

protected void preProcessEntityDescriptor(@Nonnull EntityDescriptor entityDescriptor, @Nonnull AbstractMetadataResolver.EntityBackingStore backingStore)
Pre-process the specified entity descriptor, updating the specified entity backing store instance as necessary.

Parameters:
  `entityDescriptor` - the target entity descriptor to process
  `backingStore` - the backing store instance to update

### removeByEntityID

protected void removeByEntityID(@Nonnull String entityID, @Nonnull AbstractMetadataResolver.EntityBackingStore backingStore)
Remove from the backing store all metadata for the entity with the given entity ID.

Parameters:
  `entityID` - the entity ID of the metadata to remove
  `backingStore` - the backing store instance to update

### indexEntityDescriptor

protected void indexEntityDescriptor(@Nonnull EntityDescriptor entityDescriptor, @Nonnull AbstractMetadataResolver.EntityBackingStore backingStore)
Index the specified entity descriptor, updating the specified entity backing store instance as necessary.

Parameters:
  `entityDescriptor` - the target entity descriptor to process
  `backingStore` - the backing store instance to update

### preProcessEntitiesDescriptor

protected void preProcessEntitiesDescriptor(@Nonnull EntitiesDescriptor entitiesDescriptor, @Nonnull AbstractMetadataResolver.EntityBackingStore backingStore)
Pre-process the specified entities descriptor, updating the specified entity backing store instance as necessary.

Parameters:
  `entitiesDescriptor` - the target entities descriptor to process
  `backingStore` - the backing store instance to update

### predicateFilterCandidates

@Nonnull protected Iterable<EntityDescriptor> predicateFilterCandidates(@Nonnull Iterable<EntityDescriptor> candidates, @Nullable CriteriaSet criteria, boolean onEmptyPredicatesReturnEmpty) throws ResolverException
Filter the supplied candidates by resolving predicates from the supplied criteria and applying the predicates to return a filtered `Iterable`.

Parameters:
  `candidates` - the candidates to evaluate
  `criteria` - the criteria set to evaluate
  `onEmptyPredicatesReturnEmpty` - if true and no predicates are supplied, then return an empty iterable; otherwise return the original input candidates
Returns:
  an iterable of the candidates filtered by the resolved predicates
Throws:
  `ResolverException` - if there is a fatal error during resolution

### getLogPrefix

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

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