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 * <complexType name="AttributeType"> 047 * <complexContent> 048 * <restriction base="{http://www.w3.org/2001/XMLSchema}anyType"> 049 * <sequence> 050 * <element ref="{urn:oasis:names:tc:SAML:2.0:assertion} 051 * AttributeValue" maxOccurs="unbounded" minOccurs="0"/> 052 * </sequence> 053 * <attribute name="FriendlyName" 054 * type="{http://www.w3.org/2001/XMLSchema}string" /> 055 * <attribute name="Name" use="required" 056 * type="{http://www.w3.org/2001/XMLSchema}string" /> 057 * <attribute name="NameFormat" 058 * type="{http://www.w3.org/2001/XMLSchema}anyURI" /> 059 * </restriction> 060 * </complexContent> 061 * </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