1 /* 2 * Copyright [2005] [University Corporation for Advanced Internet Development, Inc.] 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package org.opensaml.saml2.metadata.provider; 18 19 import java.util.List; 20 21 import javax.xml.namespace.QName; 22 23 import org.opensaml.saml2.metadata.EntitiesDescriptor; 24 import org.opensaml.saml2.metadata.EntityDescriptor; 25 import org.opensaml.saml2.metadata.RoleDescriptor; 26 import org.opensaml.xml.XMLObject; 27 28 /** 29 * A local store into which metadata can be loaded and queried. Specific implementations may perform additional logic 30 * such as caching (and refreshing) metadata and merging metadata, about a single entity, from multiple sources. 31 * 32 * <strong>NOTE</strong>, developers should not try to marshall the metadata that comes from a metadata provider. It is 33 * possible that the a provider, or {@link MetadataFilter}, implementation may make changes to the retrieved metadata 34 * that make unusable for marshalling. For example, by removing elements required by the schema but not by the user of 35 * the provider as a way of saving on memory. Or by remove elements and thus invalidating a signature that had be 36 * present on the retrieved metadata. 37 */ 38 public interface MetadataProvider { 39 40 /** 41 * Gets whether the metadata returned by queries must be valid. At a minimum, metadata is valid only if the date 42 * expressed in entity's validUntil attribute has not passed. Specific implementations may add additional 43 * constraints. 44 * 45 * @return whether the metadata returned by queries must be valid 46 */ 47 public boolean requireValidMetadata(); 48 49 /** 50 * Sets whether the metadata returned by queries must be valid. 51 * 52 * @param requireValidMetadata whether the metadata returned by queries must be valid 53 */ 54 public void setRequireValidMetadata(boolean requireValidMetadata); 55 56 /** 57 * Gets the metadata filter applied to the metadata. 58 * 59 * @return the metadata filter applied to the metadata 60 */ 61 public MetadataFilter getMetadataFilter(); 62 63 /** 64 * Sets the metadata filter applied to the metadata. 65 * 66 * @param newFilter the metadata filter applied to the metadata 67 * 68 * @throws MetadataProviderException thrown if the provider can not apply the filter to the metadata 69 */ 70 public void setMetadataFilter(MetadataFilter newFilter) throws MetadataProviderException; 71 72 /** 73 * Gets the entire metadata tree, after the registered filter has been applied. 74 * 75 * @return the entire metadata tree 76 * 77 * @throws MetadataProviderException thrown if the provider can not fetch the metadata 78 */ 79 public XMLObject getMetadata() throws MetadataProviderException; 80 81 /** 82 * Gets a named EntitiesDescriptor from the metadata. 83 * 84 * @param name the name of the EntitiesDescriptor 85 * 86 * @return the EntitiesDescriptor or null 87 * 88 * @throws MetadataProviderException thrown if the provider can not fetch the metadata 89 */ 90 public EntitiesDescriptor getEntitiesDescriptor(String name) throws MetadataProviderException; 91 92 /** 93 * Gets the metadata for a given entity if the metadata is valid. 94 * 95 * @param entityID the ID of the entity 96 * 97 * @return the entity's metadata or null if there is no metadata or no valid metadata 98 * 99 * @throws MetadataProviderException thrown if the provider can not fetch the metadata 100 */ 101 public EntityDescriptor getEntityDescriptor(String entityID) throws MetadataProviderException; 102 103 /** 104 * Gets the role descriptors of a given type for a given entity from valid metadata. 105 * 106 * @param entityID the ID of the entity 107 * @param roleName the role type 108 * 109 * @return the role descriptors 110 * 111 * @throws MetadataProviderException thrown if the provider can not fetch the metadata 112 */ 113 public List<RoleDescriptor> getRole(String entityID, QName roleName) throws MetadataProviderException; 114 115 /** 116 * Gets the role descriptors of a given type for a given entity that support the given protocol from valid metadata. 117 * 118 * @param entityID the ID of the entity 119 * @param roleName the role type 120 * @param supportedProtocol the protocol supported by the role 121 * 122 * @return the role descriptors 123 * 124 * @throws MetadataProviderException thrown if the provider can not fetch the metadata 125 */ 126 public RoleDescriptor getRole(String entityID, QName roleName, String supportedProtocol) 127 throws MetadataProviderException; 128 }