Package net.shibboleth.metadata.dom

Class AbstractDOMTraversalStage<C extends DOMTraversalContext>

java.lang.Object
net.shibboleth.shared.component.AbstractInitializableComponent
net.shibboleth.shared.component.AbstractIdentifiedInitializableComponent
net.shibboleth.shared.component.AbstractIdentifiableInitializableComponent
net.shibboleth.metadata.pipeline.AbstractStage<T>
net.shibboleth.metadata.pipeline.AbstractIteratingStage<Element>
net.shibboleth.metadata.dom.AbstractDOMTraversalStage<C>
Type Parameters:
C - the context to carry through the traversal
All Implemented Interfaces:
Stage<Element>, net.shibboleth.shared.component.Component, net.shibboleth.shared.component.DestructableComponent, net.shibboleth.shared.component.IdentifiableComponent, net.shibboleth.shared.component.IdentifiedComponent, net.shibboleth.shared.component.InitializableComponent
Direct Known Subclasses:
AbstractDOMValidationStage, AbstractElementVisitingStage, AbstractSAMLTraversalStage, ElementsStrippingStage, IPHintValidationStage
@ThreadSafe public abstract class AbstractDOMTraversalStage<C extends DOMTraversalContext> extends AbstractIteratingStage<Element>
An abstract DOM traversal class using the template method pattern.

A context object, extending DOMTraversalContext, is created by the implementing subclass and passed to the visit(org.w3c.dom.Element, C) method when each applicable Element is visited. In very simple cases, the SimpleDOMTraversalContext may suffice, but more complicated behaviour can be built up by extending or re-implementing that class.

Which Element nodes are visited during the traversal is controlled by n applicable(org.w3c.dom.Element, C) method implemented by subclasses. Traversal within elements to DOM attributes is not supported directly.

At the end of the traversal, the context's DOMTraversalContext.end() method is called to perform any post-processing required.

Since:
0.9.0

  • Constructor Details

    • AbstractDOMTraversalStage

      public AbstractDOMTraversalStage()

  • Method Details

    • buildContext

      @Nonnull protected abstract C buildContext(@Nonnull Item<Element> item)
      Build the context for a particular traversal.
      Parameters:
      item - the Item we are traversing
      Returns:
      an appropriate context

    • applicable

      protected abstract boolean applicable(@Nonnull Element element, @Nonnull C context)
      Indicates whether the visitor should be applied to a particular Element.
      Parameters:
      element - Element to which we may wish to apply the visitor
      context - DOMTraversalContext implementation being used to manage the traversal
      Returns:
      true if the visitor should be applied to this Element.

    • visit

      protected abstract void visit(@Nonnull Element element, @Nonnull C context) throws StageProcessingException
      Visit a particular Element.
      Parameters:
      element - the Element to visit
      context - the traversal context
      Throws:
      StageProcessingException - if errors occur during processing

    • traverse

      private void traverse(@Nonnull Element element, @Nonnull C context) throws StageProcessingException
      Depth-first traversal of the DOM tree rooted in an element, applying the visitor when appropriate. The traversal snapshots the child elements at each level, so that the visitor could in principle reorder or delete them during processing.
      Parameters:
      element - Element to start from
      context - context for the traversal
      Throws:
      StageProcessingException - if errors occur during processing

    • doExecute

      protected void doExecute(@Nonnull Item<Element> item) throws StageProcessingException
      Description copied from class: AbstractIteratingStage
      Processes a given Item.
      Specified by:
      doExecute in class AbstractIteratingStage<Element>
      Parameters:
      item - Item on which to operate
      Throws:
      StageProcessingException - thrown if there is a problem with the stage processing

    • errorPrefix

      @Nonnull protected String errorPrefix(@Nonnull Element element)
      Computes a prefix to be put in front of the message in addError(net.shibboleth.metadata.Item<org.w3c.dom.Element>, org.w3c.dom.Element, java.lang.String).
      Parameters:
      element - Element forming the context for the prefix
      Returns:
      a prefix for the error message

    • addError

      protected void addError(@Nonnull Item<Element> item, @Nonnull Element element, @Nonnull String error)
      Add an ErrorStatus to the given item, in respect of the given Element. If the item is an EntitiesDescriptor, interpose an identifier for the individual EntityDescriptor.
      Parameters:
      item - Item to add the error to
      element - Element the error reflects
      error - error text