001/*
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003 *
004 * Copyright (c) 2006 Sun Microsystems Inc. All Rights Reserved
005 *
006 * The contents of this file are subject to the terms
007 * of the Common Development and Distribution License
008 * (the License). You may not use this file except in
009 * compliance with the License.
010 *
011 * You can obtain a copy of the License at
012 * https://opensso.dev.java.net/public/CDDLv1.0.html or
013 * opensso/legal/CDDLv1.0.txt
014 * See the License for the specific language governing
015 * permission and limitations under the License.
016 *
017 * When distributing Covered Code, include this CDDL
018 * Header Notice in each file and include the License file
019 * at opensso/legal/CDDLv1.0.txt.
020 * If applicable, add the following below the CDDL Header,
021 * with the fields enclosed by brackets [] replaced by
022 * your own identifying information:
023 * "Portions Copyrighted [year] [name of copyright owner]"
024 *
025 * $Id: Attribute.java,v 1.2 2008/06/25 05:47:40 qcheng Exp $
026 *
027 * Portions Copyrighted 2015 ForgeRock AS.
028 */
029
030package com.sun.identity.saml2.assertion;
031
032import java.security.Key;
033import java.util.List;
034import java.util.Map;
035
036import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
037import com.sun.identity.saml2.assertion.impl.AttributeImpl;
038import com.sun.identity.saml2.common.SAML2Exception;
039
040/**
041 * The <code>Attribute</code> element identifies an attribute by name and
042 * optionally includes its value(s). It has the <code>AttributeType</code>
043 * complex type.
044 * <p>
045 * <pre>
046 * &lt;complexType name="AttributeType">
047 *   &lt;complexContent>
048 *     &lt;restriction base="{http://www.w3.org/2001/XMLSchema}anyType">
049 *       &lt;sequence>
050 *         &lt;element ref="{urn:oasis:names:tc:SAML:2.0:assertion}
051 *         AttributeValue" maxOccurs="unbounded" minOccurs="0"/>
052 *       &lt;/sequence>
053 *       &lt;attribute name="FriendlyName"
054 *       type="{http://www.w3.org/2001/XMLSchema}string" />
055 *       &lt;attribute name="Name" use="required"
056 *       type="{http://www.w3.org/2001/XMLSchema}string" />
057 *       &lt;attribute name="NameFormat"
058 *       type="{http://www.w3.org/2001/XMLSchema}anyURI" />
059 *     &lt;/restriction>
060 *   &lt;/complexContent>
061 * &lt;/complexType>
062 * </pre>
063 * @supported.all.api 
064 */
065@JsonDeserialize(as=AttributeImpl.class)
066public interface Attribute {
067
068    /**
069     * Makes the object immutable.
070     */
071    void makeImmutable();
072
073    /**
074     * Returns the mutability of the object.
075     *
076     * @return <code>true</code> if the object is mutable;
077     *                <code>false</code> otherwise.
078     */
079    boolean isMutable();
080
081    /**
082     * Returns the <code>AttributeValue</code>(s) of the <code>Attribute</code>.
083     *
084     * @return List of xml String representing <code>AttributeValue</code>(s)
085     *                 of the <code>Attribute</code>.
086     * @see #setAttributeValue(List)
087     */
088    List getAttributeValue();
089
090    /**
091     * Sets the <code>AttributeValue</code>(s) of the <code>Attribute</code>.
092     *
093     * @param value List of xml String representing the new
094     *                 <code>AttributeValue</code> element(s).
095     * @throws SAML2Exception if the object is immutable.
096     * @see #getAttributeValue()
097     */
098    void setAttributeValue(List value) throws SAML2Exception;
099
100    /**
101     * Returns the <code>AttributeValue</code>(s) of the <code>Attribute</code>.
102     *
103     * @return List of String representing the value of
104     *                 <code>AttributeValue</code>(s).
105     * @see #setAttributeValueString(List)
106     */
107    List getAttributeValueString();
108
109    /**
110     * Sets the value of <code>AttributeValue</code> element(s).
111     *
112     * @param value List of String representing the value of the new
113     *          <code>AttributeValue</code> element(s).
114     * @throws SAML2Exception if the object is immutable.
115     * @see #getAttributeValueString()
116     */
117    void setAttributeValueString(List value) throws SAML2Exception;
118
119    /**
120     * Returns the <code>Name</code> of the attribute.
121     *
122     * @return the <code>Name</code> of the attribute.
123     * @see #setName(String)
124     */
125    String getName();
126
127    /**
128     * Sets the <code>Name</code> of the attribute.
129     *
130     * @param value new <code>Name</code> of the attribute.
131     * @throws SAML2Exception if the object is immutable.
132     * @see #getName()
133     */
134    void setName(String value) throws SAML2Exception;
135
136    /**
137     * Returns the <code>NameFormat</code> of the attribute.
138     *
139     * @return the value of <code>NameFormat</code>.
140     * @see #setNameFormat(String)
141     */
142    String getNameFormat();
143
144    /**
145     * Sets the <code>NameFormat</code> of the attribute.
146     *
147     * @param value new <code>NameFormat</code> of the attribute.
148     * @throws SAML2Exception if the object is immutable.
149     * @see #getNameFormat()
150     */
151    void setNameFormat(String value) throws SAML2Exception;
152
153    /**
154     * Returns the <code>FriendlyName</code> of the attribute.
155     *
156     * @return the value of <code>FriendlyName</code> of the attribute.
157     * @see #setFriendlyName(String)
158     */
159    String getFriendlyName();
160
161    /**
162     * Sets the <code>FriendlyName</code> of the attribute.
163     *
164     * @param value new <code>FriendlyName</code> of the attribute.
165     * @throws SAML2Exception if the object is immutable.
166     * @see #getFriendlyName()
167     */
168    void setFriendlyName(String value) throws SAML2Exception;
169
170    /**
171     * Returns the <code>anyAttribute</code> of the attribute.
172     *
173     * @return A Map containing name/value pairs of <code>anyAttribute</code>.
174     *                Both the name and value are String object types.
175     * @see #setAnyAttribute(Map)
176     */
177    Map getAnyAttribute();
178
179    /**
180     * Sets the <code>anyAttribute</code> of the attribute.
181     *
182     * @param value Map of name/value pairs to be set. Both the name and value
183     *                are String object types.
184     * @throws SAML2Exception if the object is immutable.
185     * @see #getAnyAttribute()
186     */
187    void setAnyAttribute(Map value) throws SAML2Exception;
188
189    /**
190     * Returns an <code>EncryptedAttribute</code> object.
191     *
192     * @param recipientPublicKey Public key used to encrypt the data encryption
193     *                           (secret) key, it is the public key of the
194     *                           recipient of the XML document to be encrypted.
195     * @param dataEncAlgorithm Data encryption algorithm.
196     * @param dataEncStrength Data encryption strength.
197     * @param recipientEntityID Unique identifier of the recipient, it is used
198     *                          as the index to the cached secret key so that
199     *                          the key can be reused for the same recipient;
200     *                          It can be null in which case the secret key will
201     *                          be generated every time and will not be cached
202     *                          and reused. Note that the generation of a secret
203     *                          key is a relatively expensive operation.
204     * @return <code>EncryptedAttribute</code> object
205     * @throws SAML2Exception if error occurs during the encryption process.
206     */
207    EncryptedAttribute encrypt(Key recipientPublicKey, String dataEncAlgorithm,
208                               int dataEncStrength, String recipientEntityID) throws SAML2Exception;
209    
210 
211    /**
212     * Returns a String representation of the element.
213     *
214     * @return A string containing the valid XML for this element.
215     *         By default name space name is prepended to the element name.
216     * @throws SAML2Exception if the object does not conform to the schema.
217     */
218    String toXMLString() throws SAML2Exception;
219
220    /**
221     * Returns a String representation of the element.
222     *
223     * @param includeNS Determines whether or not the namespace qualifier is
224     *                prepended to the Element when converted
225     * @param declareNS Determines whether or not the namespace is declared
226     *                within the Element.
227     * @return A string containing the valid XML for this element
228     * @throws SAML2Exception if the object does not conform to the schema.
229     */
230    String toXMLString(boolean includeNS, boolean declareNS) throws SAML2Exception;
231
232}
233