View Javadoc

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 }