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 */
028
029
030
031package com.sun.identity.saml2.assertion;
032
033import java.security.Key;
034import java.util.List;
035import java.util.Map;
036
037import com.sun.identity.saml2.common.SAML2Exception;
038
039/**
040 * The <code>Attribute</code> element identifies an attribute by name and
041 * optionally includes its value(s). It has the <code>AttributeType</code>
042 * complex type.
043 * <p>
044 * <pre>
045 * &lt;complexType name="AttributeType">
046 *   &lt;complexContent>
047 *     &lt;restriction base="{http://www.w3.org/2001/XMLSchema}anyType">
048 *       &lt;sequence>
049 *         &lt;element ref="{urn:oasis:names:tc:SAML:2.0:assertion}
050 *         AttributeValue" maxOccurs="unbounded" minOccurs="0"/>
051 *       &lt;/sequence>
052 *       &lt;attribute name="FriendlyName"
053 *       type="{http://www.w3.org/2001/XMLSchema}string" />
054 *       &lt;attribute name="Name" use="required"
055 *       type="{http://www.w3.org/2001/XMLSchema}string" />
056 *       &lt;attribute name="NameFormat"
057 *       type="{http://www.w3.org/2001/XMLSchema}anyURI" />
058 *     &lt;/restriction>
059 *   &lt;/complexContent>
060 * &lt;/complexType>
061 * </pre>
062 * @supported.all.api 
063 */
064public interface Attribute {
065
066    /**
067     * Makes the object immutable.
068     */
069    public void makeImmutable();
070
071    /**
072     * Returns the mutability of the object.
073     *
074     * @return <code>true</code> if the object is mutable;
075     *                <code>false</code> otherwise.
076     */
077    public boolean isMutable();
078
079    /**
080     * Returns the <code>AttributeValue</code>(s) of the <code>Attribute</code>.
081     *
082     * @return List of xml String representing <code>AttributeValue</code>(s)
083     *                 of the <code>Attribute</code>.
084     * @see #setAttributeValue(List)
085     */
086    public List getAttributeValue();
087
088    /**
089     * Sets the <code>AttributeValue</code>(s) of the <code>Attribute</code>.
090     *
091     * @param value List of xml String representing the new
092     *                 <code>AttributeValue</code> element(s).
093     * @throws SAML2Exception if the object is immutable.
094     * @see #getAttributeValue()
095     */
096    public void setAttributeValue(List value)
097        throws SAML2Exception;
098
099    /**
100     * Returns the <code>AttributeValue</code>(s) of the <code>Attribute</code>.
101     *
102     * @return List of String representing the value of
103     *                 <code>AttributeValue</code>(s).
104     * @see #setAttributeValueString(List)
105     */
106    public List getAttributeValueString();
107
108    /**
109     * Sets the value of <code>AttributeValue</code> element(s).
110     *
111     * @param value List of String representing the value of the new
112     *          <code>AttributeValue</code> element(s).
113     * @throws SAML2Exception if the object is immutable.
114     * @see #getAttributeValueString()
115     */
116    public void setAttributeValueString(List value)
117        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    public 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    public void setName(String value)
135        throws SAML2Exception;
136
137    /**
138     * Returns the <code>NameFormat</code> of the attribute.
139     *
140     * @return the value of <code>NameFormat</code>.
141     * @see #setNameFormat(String)
142     */
143    public String getNameFormat();
144
145    /**
146     * Sets the <code>NameFormat</code> of the attribute.
147     *
148     * @param value new <code>NameFormat</code> of the attribute.
149     * @throws SAML2Exception if the object is immutable.
150     * @see #getNameFormat()
151     */
152    public void setNameFormat(String value)
153        throws SAML2Exception;
154
155    /**
156     * Returns the <code>FriendlyName</code> of the attribute.
157     *
158     * @return the value of <code>FriendlyName</code> of the attribute.
159     * @see #setFriendlyName(String)
160     */
161    public String getFriendlyName();
162
163    /**
164     * Sets the <code>FriendlyName</code> of the attribute.
165     *
166     * @param value new <code>FriendlyName</code> of the attribute.
167     * @throws SAML2Exception if the object is immutable.
168     * @see #getFriendlyName()
169     */
170    public void setFriendlyName(String value)
171        throws SAML2Exception;
172
173    /**
174     * Returns the <code>anyAttribute</code> of the attribute.
175     *
176     * @return A Map containing name/value pairs of <code>anyAttribute</code>.
177     *                Both the name and value are String object types.
178     * @see #setAnyAttribute(Map)
179     */
180    public Map getAnyAttribute();
181
182    /**
183     * Sets the <code>anyAttribute</code> of the attribute.
184     *
185     * @param value Map of name/value pairs to be set. Both the name and value
186     *                are String object types.
187     * @throws SAML2Exception if the object is immutable.
188     * @see #getAnyAttribute()
189     */
190    public void setAnyAttribute(Map value)
191        throws SAML2Exception;
192
193    /**
194     * Returns an <code>EncryptedAttribute</code> object.
195     *
196     * @param recipientPublicKey Public key used to encrypt the data encryption
197     *                           (secret) key, it is the public key of the
198     *                           recipient of the XML document to be encrypted.
199     * @param dataEncAlgorithm Data encryption algorithm.
200     * @param dataEncStrength Data encryption strength.
201     * @param recipientEntityID Unique identifier of the recipient, it is used
202     *                          as the index to the cached secret key so that
203     *                          the key can be reused for the same recipient;
204     *                          It can be null in which case the secret key will
205     *                          be generated every time and will not be cached
206     *                          and reused. Note that the generation of a secret
207     *                          key is a relatively expensive operation.
208     * @return <code>EncryptedAttribute</code> object
209     * @throws SAML2Exception if error occurs during the encryption process.
210     */
211    public EncryptedAttribute encrypt(
212        Key recipientPublicKey,
213        String dataEncAlgorithm,
214        int dataEncStrength,
215        String recipientEntityID)
216        throws SAML2Exception;
217    
218 
219    /**
220     * Returns a String representation of the element.
221     *
222     * @return A string containing the valid XML for this element.
223     *         By default name space name is prepended to the element name.
224     * @throws SAML2Exception if the object does not conform to the schema.
225     */
226    public String toXMLString()
227        throws SAML2Exception;
228
229    /**
230     * Returns a String representation of the element.
231     *
232     * @param includeNS Determines whether or not the namespace qualifier is
233     *                prepended to the Element when converted
234     * @param declareNS Determines whether or not the namespace is declared
235     *                within the Element.
236     * @return A string containing the valid XML for this element
237     * @throws SAML2Exception if the object does not conform to the schema.
238     */
239    public String toXMLString(boolean includeNS, boolean declareNS)
240        throws SAML2Exception;
241
242}
243