View Javadoc

1   /*
2    * Copyright 2006 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.common.binding.artifact;
18  
19  import org.opensaml.common.SAMLObject;
20  import org.opensaml.util.storage.ExpiringObject;
21  import org.opensaml.xml.io.MarshallingException;
22  
23  /**
24   * Maps an artifact to a SAML message and back again.
25   * 
26   * Artifacts must be thread safe.
27   * 
28   * An implementation of this interface MUST ensure that the persisted SAML message is no longer tied to any 
29   * parent {@link org.opensaml.xml.XMLObject} that may have contained it.  This ensure it can be safely added 
30   * to another object once retrieved from the map.  The easiest way to do this is to serailize the message out
31   * in to a string and re-parse and unmarhsall it again once retrieved from the underlying data store.
32   */
33  public interface SAMLArtifactMap {
34  
35      /**
36       * Checks if a given artifact has a map entry.
37       * 
38       * @param artifact the artifact to check
39       * 
40       * @return true of this map has an entry for the given artifact, false it not
41       */
42      public boolean contains(String artifact);
43  
44      /**
45       * Creates a mapping between a given artifact and the SAML message to which it maps.
46       * 
47       * @param artifact the artifact
48       * @param relyingPartyId ID of the party the artifact was sent to
49       * @param issuerId ID of the issuer of the artifact
50       * @param samlMessage the SAML message
51       * 
52       * @throws MarshallingException thrown if the given SAML message can not be marshalled
53       */
54      public void put(String artifact, String relyingPartyId, String issuerId, SAMLObject samlMessage)
55              throws MarshallingException;
56  
57      /**
58       * Gets the artifact entry for the given artifact.
59       * 
60       * @param artifact the artifact to retrieve the entry for
61       * 
62       * @return the entry or null if the artifact has already expired or did not exist
63       */
64      public SAMLArtifactMapEntry get(String artifact);
65  
66      /**
67       * Removes the artifact from this map.
68       * 
69       * @param artifact artifact to be removed
70       */
71      public void remove(String artifact);
72      
73      /**
74       * Represents a mapping between an artifact a SAML message with some associated metadata. 
75       */
76      public interface SAMLArtifactMapEntry extends ExpiringObject {
77  
78          /**
79           * Gets the artifact that maps to the SAML message.
80           * 
81           * @return artifact that maps to the SAML message
82           */
83          public String getArtifact();
84  
85          /**
86           * Gets the ID of the issuer of the artifact.
87           * 
88           * @return ID of the issuer of the artifact
89           */
90          public String getIssuerId();
91  
92          /**
93           * Gets the ID of the relying party the artifact was sent to.
94           * 
95           * @return ID of the relying party the artifact was sent to
96           */
97          public String getRelyingPartyId();
98  
99          /**
100          * Gets SAML message the artifact maps to.
101          * 
102          * @return SAML message the artifact maps to
103          */
104         public SAMLObject getSamlMessage();
105     }
106 }