se.swedenconnect.opensaml.eidas.metadata.MetadataLocation Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of opensaml-eidas Show documentation
OpenSAML 5.X extension library for the eIDAS Framework
The newest version!
/*
 * Copyright 2016-2024 Sweden Connect
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package se.swedenconnect.opensaml.eidas.metadata;

import org.opensaml.core.xml.AttributeExtensibleXMLObject;
import org.opensaml.saml.common.SAMLObject;
import org.opensaml.xmlsec.signature.KeyInfo;
import se.swedenconnect.opensaml.eidas.common.EidasConstants;

import javax.xml.namespace.QName;
import java.security.cert.X509Certificate;
import java.util.List;

/**
 * Definition of the {@code MetadataLocation} type.
 * 
 * The following schema fragment defines the MetadataLocationType complex type:
 * 
 *  * {@code
 *  
 *    
 *      
 *        
 *          
 *            A list of eIDAS endpoints (nodes) for the current location.
 *          
 *        
 *      
 *      
 *        
 *          
 *            Key material (usually a certificate) that should be used to verify the signature
 *            of the downloaded metadata for this metadata location.
 *          
 *        
 *      
 *    
 *    
 *      
 *        
 *          The URL from where the metadata for the endpoint(s) can be obtained.
 *        
 *      
 *    
 *    
 *  }
 * 
 *
 * @author Martin Lindström
 */
public interface MetadataLocation extends SAMLObject, AttributeExtensibleXMLObject {

  /** Name of the element. */
  String DEFAULT_ELEMENT_LOCAL_NAME = "MetadataLocation";

  /** Default element name. */
  QName DEFAULT_ELEMENT_NAME = new QName(EidasConstants.EIDAS_SERVICELIST_NS, DEFAULT_ELEMENT_LOCAL_NAME,
      EidasConstants.EIDAS_SERVICELIST_PREFIX);

  /** Local name of the XSI type. */
  String TYPE_LOCAL_NAME = "MetadataLocationType";

  /** QName of the XSI type. */
  QName TYPE_NAME =
      new QName(EidasConstants.EIDAS_SERVICELIST_NS, TYPE_LOCAL_NAME, EidasConstants.EIDAS_SERVICELIST_PREFIX);

  /** Attribute label for the Location attribute. */
  String LOCATION_ATTR_NAME = "Location";

  /**
   * Returns the list of endpoints.
   *
   * @return endpoint list
   */
  List getEndpoints();

  /**
   * Returns the key info element to be used when verifying downloaded metadata.
   *
   * @return key info element, or {@code null}
   * @deprecated Use {@link #getKeyInfos()} instead
   */
  @Deprecated(since = "3.0.1", forRemoval = true)
  default KeyInfo getKeyInfo() {
    return !this.getKeyInfos().isEmpty() ? this.getKeyInfos().get(0) : null;
  }

  /**
   * Returns a list of the key info elements that may be used when verifying downloaded metadata.
   *
   * @return a (possibly empty) list of key info elements
   */
  List getKeyInfos();

  /**
   * Assigns the key info element to be used when verifying downloaded metadata.
   *
   * @param keyInfo key info element
   * @see #setX509Certificate(X509Certificate)
   * @deprecated Use {@link #getKeyInfos()} instead and add the element to the live list
   */
  @Deprecated(since = "3.0.1", forRemoval = true)
  default void setKeyInfo(final KeyInfo keyInfo) {
    this.getKeyInfos().clear();
    this.getKeyInfos().add(keyInfo);
  }

  /**
   * Utility method that creates a {@link KeyInfo} object and assigns the supplied certificate to it before invoking
   * {@link #setKeyInfo(KeyInfo)}.
   *
   * @param certificate the X.509 certificate to assign to a key info
   */
  @Deprecated(since = "3.0.1", forRemoval = true)
  default void setX509Certificate(final X509Certificate certificate) {
    this.getKeyInfos().clear();
    this.addX509Certificate(certificate);
  }

  /**
   * Utility method that creates a {@link KeyInfo} object and assigns the supplied certificate to it before adding it to
   * {@link #getKeyInfos()}.
   *
   * @param certificate certificate the X.509 certificate to assign to a key info
   */
  void addX509Certificate(final X509Certificate certificate);

  /**
   * Returns the location attribute, i.e., the URL from where the metadata endpoint(s) can be obtained.
   *
   * @return URL
   */
  String getLocation();

  /**
   * Assigns the location attribute, i.e., the URL from where the metadata endpoint(s) can be obtained.
   *
   * @param location URL
   */
  void setLocation(final String location);

  /**
   * For the Swedish eIDAS configuration, a flag, {@code Suspend} is used to indicate whether an endpoint has been
   * suspended. This method is just a shortcut instead of using {@link #getUnknownAttributes()}.
   *
   * @return if the {@code Suspend} flag has been set to {@code true} this method returns {@code true}, otherwise
   *     {@code false} 
   */
  boolean getSuspend();

  /**
   * Assigns the {@code Suspend} flag. See {@link #getSuspend()}.
   *
   * @param suspendFlag the suspend flag
   */
  void setSuspend(final boolean suspendFlag);

}